ebay 0.5.2 → 0.6.0

data/README

@@ -1,10 +1,10 @@
 
 == Welcome to eBay4R
 
-eBay4R is a Ruby wrapper for eBay's Web Services SOAP API (v433). Emphasis is
+eBay4R is a Ruby wrapper for eBay's Web Services SOAP API (v449). Emphasis is
 on ease of use and small footprint.
 
-<b>This code is currently alpha stage</b>.
+<b>This code is currently beta</b>.
 
 Please report bugs and other problems, see "Author" section at the bottom.
 
@@ -117,7 +117,28 @@ This is a more complex example that performs a real (useful) function:
 
   eBay = EBay::API.new($authToken, $devId, $appId, $certId, :sandbox => true)
 
-  # New method of generating complex types, needs some more testing...
+  # 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...',
@@ -129,8 +150,6 @@ This is a more complex example that performs a real (useful) function:
                                          :Currency => "USD",
                                          :PaymentMethods => ["VisaMC", "PersonalCheck"]))
 
-  puts "New Item #" + resp.itemID + " added."
-
 
 === Format of Requests
 
@@ -152,7 +171,7 @@ 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
+==== 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 
@@ -340,7 +359,7 @@ AIM: garry97531
 
 == Copyright
 
-Copyright (c) 2005 Garry C. Dolley
+Copyright (c) 2005,2006 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
@@ -356,4 +375,4 @@ 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.14 2005/12/21 02:17:10 garrydolley Exp $
+$Id: README,v 1.16 2006/04/24 05:51:18 garrydolley Exp $

data/contrib/get_and_store_ebay_categories.rb

@@ -0,0 +1,240 @@
+#!/usr/bin/env ruby
+# $Id: get_and_store_ebay_categories.rb,v 1.2 2006/01/18 09:42:02 garrydolley Exp $
+#
+# == Copyright
+#
+# Copyright (c) 2005,2006 Garry C. Dolley
+#
+# This file is part of eBay4R.
+#
+# 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
+#
+# Created : 01/16/2006
+#
+# == Synopsis 
+#
+# This script will retrieve the entire eBay Category tree for a specified eBay
+# site (site_id) and store it in a MySQL database.
+#
+# == Database
+#
+# The schema used is as follows:
+#
+#   CREATE TABLE ebay_categories (
+#     id int(11) NOT NULL auto_increment,
+#     site_id smallint(6) default NULL,
+#     category_id varchar(10) NOT NULL default '',
+#     category_parent_id varchar(10) default NULL,
+#     category_name varchar(128) NOT NULL default '',
+#     category_level int(11) default NULL,
+#     leaf_category tinyint(1) NOT NULL default '0',
+#     expired tinyint(1) NOT NULL default '0',
+#     virtual tinyint(1) NOT NULL default '0',
+#     auto_pay_enabled tinyint(1) NOT NULL default '0',
+#     b2b_vat_enabled tinyint(1) NOT NULL default '0',
+#     best_offer_enabled tinyint(1) NOT NULL default '0',
+#     intl_autos_fixed_cat tinyint(1) NOT NULL default '0',
+#     lsd tinyint(1) NOT NULL default '0',
+#     orpa tinyint(1) NOT NULL default '0',
+#     orra tinyint(1) NOT NULL default '0',
+#     PRIMARY KEY  (id),
+#     UNIQUE KEY site_id (site_id,category_id),
+#     KEY category_id (category_id),
+#     KEY category_parent_id (category_parent_id),
+#     CONSTRAINT ebay_categories_ibfk_1 FOREIGN KEY (category_parent_id) 
+#                                       REFERENCES ebay_categories (category_id)
+#  ) ENGINE=InnoDB DEFAULT CHARSET=latin1 
+#
+# and
+#
+#   CREATE TABLE ebay_categories_info (
+#     id int(11) NOT NULL auto_increment,
+#     site_id smallint(6) default NULL,
+#     category_version varchar(16) NOT NULL default '',
+#     minimum_reserve_price double default NULL,
+#     reduce_reserve_allowed tinyint(1) NOT NULL default '0',
+#     reserve_price_allowed tinyint(1) NOT NULL default '0',
+#     update_time datetime default NULL,
+#     PRIMARY KEY  (id)
+#     UNIQUE KEY site_id (site_id)
+#   ) ENGINE=MyISAM DEFAULT CHARSET=latin1
+#
+# == Usage
+#
+#    ./get_and_store_ebay_categories.rb -s site_id [ -t | --table TABLE_BASE_NAME ] [ -h | --host HOST ] [ -d | --database DB ] [ -u | --user USER ] [ -p | --password PW ] [ --debug ] [ -c concurrency ]
+#
+#    Example site IDs: 0 = eBay USA, 2 = eBay Canada, 100 = eBay Motors
+#
+#    Just like the examples/ directory, you need a file named 
+#    "myCredentials.rb" in the current directory or Ruby load path.
+#
+#    The "-c concurrency" command line option says how many category nodes we 
+#    retrieve at a time.  Default is 20.  All direct children are also 
+#    downloaded (grouped BFS).
+#
+#    If you are getting out of memory errors, reduce this number.
+#    If you have lots of memory, you can increase this number and the import 
+#    will be faster.
+#
+#    Note: The eBay Category tree is very large.  This script can run for 20
+#    minutes or longer.
+
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+require 'eBayAPI'
+
+require 'optparse'
+require 'rdoc/usage'
+
+begin
+  require 'rubygems'
+  require_gem 'mysql'
+rescue LoadError
+  require 'mysql'
+end
+
+#
+# Set defaults and parse command line args
+#
+
+mysql_hostname = 'localhost'
+mysql_database = 'test'
+mysql_username = 'test'
+mysql_password = ''
+
+site_id     = 0
+table_name  = "ebay_categories"
+concurrency = 20
+
+debug      = false
+
+opts = OptionParser.new
+opts.on("-h", "--help")   { RDoc::usage('usage') }
+opts.on("-s SITE_ID")     { |sid| site_id = sid }
+opts.on("-c concurrency") { |c| concurrency = c.to_i }
+
+opts.on("-h", "--host HOST")   { |h| mysql_hostname = h }
+opts.on("-d", "--database DB") { |d| mysql_database = d }
+opts.on("-u", "--user USER")   { |u| mysql_username = u }
+opts.on("-p", "--password PW") { |p| mysql_password = p }
+opts.on("--debug")             { debug = true }
+
+opts.on("-t", "--table TABLE_NAME") { |t| table_name = t }
+
+opts.parse(ARGV) rescue RDoc::usage('usage')
+
+if ARGV.size < 1 
+  RDoc::usage('usage')
+  exit
+end
+
+#
+# Open MySQL database
+#
+
+mysql = Mysql.new(mysql_hostname, mysql_username, mysql_password)
+mysql.select_db(mysql_database)
+
+# 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)
+eBay.debug = true if debug
+
+parents_to_process = [ :id => '', :depth => 0 ]
+
+#
+# Traverse entire category tree and import into our database
+#
+
+puts "Starting import...  Go get some coffee, this is going to take a while..."
+
+imported_site_wide_info = false
+i = 0
+while (some_parents = parents_to_process.first(concurrency)).length > 0
+  seek_depth = some_parents.max { |a,b| a[:depth] <=> b[:depth] }
+  seek_depth = seek_depth[:depth] + 1
+
+  if debug
+    puts "Current process queue:"
+    p parents_to_process
+    puts "Up next:"
+    p some_parents
+  end
+
+  resp = eBay.GetCategories(:DetailLevel => 'ReturnAll', # Return all available info
+                            :CategorySideID => site_id,
+                            :CategoryParent => (some_parents[0][:id] == '' && some_parents.length == 1) ? '' : some_parents.collect { |a| a[:id] },
+                            :ViewAllNotes => true,
+                            :LevelLimit => seek_depth)
+
+  parents_to_process -= some_parents
+
+  if !imported_site_wide_info
+    mysql.query("DELETE FROM #{table_name}_info WHERE site_id = #{site_id}")
+
+    mysql.query("INSERT INTO #{table_name}_info VALUES (null, '#{site_id}', '#{resp.categoryVersion}', '#{resp.minimumReservePrice}', #{resp.reduceReserveAllowed},
+                                                               #{resp.reservePriceAllowed}, '#{resp.updateTime}')")
+    
+    imported_site_wide_info = true
+  end
+
+  if resp.categoryCount.to_i > 0
+    [resp.categoryArray.category].flatten.each do |cat|
+      if cat.categoryLevel.to_i == seek_depth
+        if cat.leafCategory == "false"
+          parents_to_process << { :id => cat.categoryID, :depth => cat.categoryLevel.to_i }
+          puts "Added Category ##{cat.categoryID} to process queue..." if debug
+        end
+      end
+
+      # Make sure we don't try to INSERT a category we already have
+      r = mysql.query("SELECT category_id FROM #{table_name} WHERE category_id = #{cat.categoryID} AND site_id = #{site_id}")
+
+      if r.num_rows < 1
+        if cat.categoryID == cat.categoryParentID
+          cat.categoryParentID = "null"
+        else
+          cat.categoryParentID = "'#{cat.categoryParentID}'"
+        end
+
+        cat.categoryName = mysql.escape_string(cat.categoryName)
+
+        # Determine values of conditional fields
+        auto_pay   = cat.respond_to?(:autoPayEnabled) ? cat.autoPayEnabled : false
+        b2b_vat    = cat.respond_to?(:b2BVATEnabled) ? cat.b2BVATEnabled : false
+        best_offer = cat.respond_to?(:bestOfferEnabled) ? cat.bestOfferEnabled : false
+        orra       = cat.respond_to?(:oRRA) ? cat.oRRA : false
+        sge        = cat.respond_to?(:sellerGuaranteeEligible) ? cat.sellerGuaranteeEligible : false
+
+        puts "Inserting Category ##{cat.categoryID}: #{cat.categoryName}..." if debug
+  
+        #
+        # Do the actual writing to the database
+        #
+        mysql.query("INSERT INTO   #{table_name} 
+                     VALUES (null, '#{site_id}', '#{cat.categoryID}', #{cat.categoryParentID}, '#{cat.categoryName}', '#{cat.categoryLevel}', #{cat.leafCategory},
+                                    #{cat.expired}, #{cat.virtual}, #{auto_pay}, #{b2b_vat}, #{best_offer}, #{cat.intlAutosFixedCat}, #{cat.lSD}, #{cat.oRPA}, #{orra},
+                                    #{sge})")
+
+        i += 1
+        puts "Imported #{i} categories so far..." if i % 100 == 0
+      end
+    end
+  end
+end
+
+mysql.close

data/examples/add_item.rb

@@ -1,5 +1,5 @@
 #!/usr/bin/env ruby
-# $Id: add_item.rb,v 1.10 2005/12/27 01:17:01 garrydolley Exp $
+# $Id: add_item.rb,v 1.11 2006/01/13 09:56:29 garrydolley Exp $
 
 $:.unshift File.join(File.dirname(__FILE__), "..", "lib")
 require 'eBayAPI'
@@ -12,17 +12,17 @@ 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"]))
+# Shorter way of passing complex types (implied by hashing) than when we did in v0.5.2 and prior
+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."
 puts "You spent:\n"

data/examples/get_categories.rb

@@ -1,5 +1,5 @@
 #!/usr/bin/env ruby
-# $Id: get_categories.rb,v 1.1 2005/12/27 01:13:46 garrydolley Exp $
+# $Id: get_categories.rb,v 1.2 2006/01/16 09:52:56 garrydolley Exp $
 
 $:.unshift File.join(File.dirname(__FILE__), "..", "lib")
 
@@ -17,7 +17,7 @@ eBay = EBay::API.new($authToken, $devId, $appId, $certId, :sandbox => true)
 
 # Call "GetCategories"
 resp = eBay.GetCategories(:DetailLevel => 'ReturnAll', # Return all available info
-                          :CategorySideID => 1,        # US site
+                          :CategorySideID => 0,        # US site
                           :LevelLimit => 1)            # Only 1 level deep
 
 # Report results

data/examples/get_categories2.rb

@@ -1,5 +1,5 @@
 #!/usr/bin/env ruby
-# $Id: get_categories2.rb,v 1.2 2006/01/07 07:50:27 garrydolley Exp $
+# $Id: get_categories2.rb,v 1.3 2006/01/16 09:54:08 garrydolley Exp $
 
 $:.unshift File.join(File.dirname(__FILE__), "..", "lib")
 
@@ -17,7 +17,7 @@ eBay = EBay::API.new($authToken, $devId, $appId, $certId, :sandbox => true, :sit
 
 # Call "GetCategories"
 resp = eBay.GetCategories(:DetailLevel => 'ReturnAll', # Return all available info
-                          :CategorySideID => 100,      # US eBay Motors Site
+                          :CategorySideID => 100,      # US eBay Motors Site 
                           :LevelLimit => 2)            # 2 Levels Deep
 
 # Report results

data/examples/get_feedback.rb

@@ -1,5 +1,5 @@
 #!/usr/bin/env ruby
-# $Id: get_feedback.rb,v 1.2 2005/12/27 01:17:01 garrydolley Exp $
+# $Id: get_feedback.rb,v 1.3 2006/01/25 08:38:42 garrydolley Exp $
 
 $:.unshift File.join(File.dirname(__FILE__), "..", "lib")
 require 'eBayAPI'
@@ -45,3 +45,4 @@ puts "Total Feedback:"
 resp.feedbackSummary.totalFeedbackPeriodArray.feedbackPeriod.each do |fb|
   puts "  Last #{fb.periodInDays} Days: #{fb.count}"
 end
+

data/examples/get_notification_preferences.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# $Id: get_notification_preferences.rb,v 1.2 2006/03/10 03:52:37 garrydolley Exp $
+
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+require 'eBayAPI'
+
+#
+# Example of GetNotificationPreferences call
+#
+
+# 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.GetNotificationPreferences(:PreferenceLevel => 'User')
+
+if resp.respond_to? 'userDeliveryPreferenceArray'
+  [resp.userDeliveryPreferenceArray.notificationEnable].flatten.each do |pref|
+    puts "Event Enable: " + pref.eventEnable
+    puts "Event Type: " + pref.eventType
+  end
+end
+
+resp = eBay.GetNotificationPreferences(:PreferenceLevel => 'Application')
+
+if resp.respond_to? 'applicationDeliveryPreferences'
+  [resp.applicationDeliveryPreferences].flatten.each do |pref|
+    puts "Alert Email: " + pref.alertEmail if pref.respond_to? 'alertEmail'
+    puts "Alert Enable: " + pref.alertEnable if pref.respond_to? 'alertEnable'
+    puts "Application Enable: " + pref.applicationEnable if pref.respond_to? 'applicationEnable'
+    puts "Application URL: " + pref.applicationURL if pref.respond_to? 'applicationURL'
+    puts "Device Type: " + pref.deviceType if pref.respond_to? 'deviceType'
+    puts "Notification Payload: " + pref.notificationPayloadType if pref.respond_to? 'notificationPayloadType'
+  end
+end
+
+resp = eBay.GetNotificationPreferences(:PreferenceLevel => 'Event')
+
+if resp.respond_to? 'eventProperty'
+  [resp.eventProperty].flatten.each do |e|
+    puts "Event Type: " + e.eventType
+    puts "Name: " + e.name
+    puts "Value: " + e.value
+  end
+end
+
+# More fields are present, see eBay's SOAP API Guide
+#
+# If you add on to this example with more fields, please send it to
+# gdolley@ucla.edu so I can include it with the next release :)

data/examples/get_notifications_usage.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# $Id: get_notifications_usage.rb,v 1.4 2006/03/16 09:37:51 garrydolley Exp $
+
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+require 'eBayAPI'
+
+#
+# Example of GetNotificationsUsage call 
+#
+
+# 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) 
+eBay.debug = true
+
+# Fill this in with a real item number to get more info about notifications
+item_no = ''
+
+if !item_no.empty?
+  resp = eBay.GetNotificationsUsage(:ItemID => item_no)
+
+  [resp.notificationDetailsArray.notificationDetails].flatten.each do |notif|
+    puts "Delivery Status: " + notif.deliveryStatus
+    puts "Delivery Time: " + notif.deliveryTime if notif.respond_to? 'deliveryTime'
+    puts "Delivery URL: " + notif.deliveryURL
+    puts "Error Message: " + notif.errorMessage
+    puts "Expiration Time: " + notif.expirationTime
+    puts "Next Retry Time: " + notif.nextRetryTime
+    puts "Retries: " + notif.retries if notif.respond_to? 'retries'
+    # puts "Type: " + notif.type  # Mmmm... "type" is already a method of Object
+  end if resp.notificationDetailsArray.respond_to? 'notificationDetails'
+end
+
+resp = eBay.GetNotificationsUsage
+
+ns = resp.notificationStatistics
+
+puts "Current Counters: "
+puts "  Delivered: " + ns.deliveredCount
+puts "  Errors: " + ns.errorCount
+puts "  Expired: " + ns.expiredCount
+puts "  Queued New: " + ns.queuedNewCount
+puts "  Queued Pending: " + ns.queuedPendingCount
+
+
+
+# More fields are present, see eBay's SOAP API Guide
+#
+# If you add on to this example with more fields, please send it to
+# gdolley@ucla.edu so I can include it with the next release :)