snl-peddler 0.1.0 → 0.1.1

data/History.txt

@@ -1,2 +1,4 @@
 == 0.1.0 / 2009-08-14
-  * First public release.
+  * First public release.
+== 0.1.1 / 2009-08-15
+	* Bumping gem to tag correctly on Github.

data/README.rdoc

@@ -22,42 +22,28 @@ Create an inventory file:
   batch << item
   ...
 
-Repeat ad infinitum and then upload:
+Repeat ad infinitum and upload:
 
   batch.upload
 
-The batch now should have an upload ID assigned to it. Let's check its error log.
+The batch now should have an upload ID. Go ahead and check the error log:
 
   upload_log = client.new_report(
     :upload,
     :id => batch.id)
   upload_log.body
   => "Feed Processing Summary:\n\tNumber of records processed\t\t1\n\tNumber of records successful\t\t1\n\n"
-  
-You're done uploading your inventory and now want to download some reports from Amazon. Let's go ahead and fetch a preorder list for the past two days to see if there is anything you can fill:
-
-  preorders_report = client.new_report(
-    :preorder,
-    :product_line => "Books",
-    :frequency    => 2)
-  preorders = Peddler::Handlers::TabDelimitedHandler.decode_response(preorders_report.body)
-  p preorders.size
-  => 2000
-  p preorders[0].asin
-  => "1234567890"
-  p preorders[0].average_asking_price
-  => "100"
-  
-Maybe you're probably wondering if you have any new orders:
+ 
+You're done listing and are wondering if you have any new orders:
 
   orders_report = client.new_report :order
-  orders = Peddler::Handlers::TabDelimitedHandler.decode_response(orders_report.body)
+  orders = client.detab(orders_report.body)
   p orders.size
   => 1500
   p orders[0].item_name
   => "A Thousand Plateaus: Capitalism and Schizophrenia (Paperback) by Gilles Deleuze"
 
-You have processed the orders and want to post back the results to Amazon, now that they're "charge when ship." Let's start with sending shipment info:
+Now that you have diligently processed the orders, post back the results to Amazon:
   
   feed = client.new_order_fulfillment_feed
   fulfilled_order = new_fulfilled_order(
@@ -86,11 +72,13 @@ Finally, check the report:
   p feed.download.to_s
   => ...
   
-Sadly, you also have an order you can't fulfill. No problem. The workflow is quite similar:
+Sadly, you also have an order you can't fulfill. No problem. The workflow is similar:
 
   feed = client.new_order_cancellation_feed
   cancelled_order = new_cancelled_order(
-    :order_id => "123-1234567-1234567")
+    :order_id => "123-1234567-1234567",
+		:cancellation_reason_code => "NoInventory",
+		:amazon_order_item_code => "12341234567890")
   feed << cancelled_order
   feed.upload
   sleep(60)
@@ -99,6 +87,37 @@ Sadly, you also have an order you can't fulfill. No problem. The workflow is qui
   p feed.download.to_s
   => ...
 
+Need to post a partial refund? You'll have to revert to the older batch refund API thingie:
+
+	refunds = client.new_refund_batch
+  refund = client.new_refund(
+		:order_id                 => "123-1234567-1234567",
+		:payments_transaction_id  => "12341234567890",
+		:refund_amount            => 1.00,
+		:reason                   => "GeneralAdjustment",
+		:message                  => "With our apologies.")
+	refunds << refund
+	refunds.upload
+
+Great sales. For a change, let's download something different from Amazon. Here's a preorder report:
+
+  preorder_report = client.new_report(
+    :preorder,
+    :product_line => "Books",
+    :frequency    => 2)
+  preorders = client.detab(preorder_report.body)
+  p preorders.size
+  => 2000
+  p preorders[0].asin
+  => "1234567890"
+  p preorders[0].average_asking_price
+  => "100"
+
 Run rdoc and check the source for more detailed info.
 
+== Todos
+
+* Replace Net::Http with a cURL-based client as former craps up with very large file downloads.
+* Add some more parsers.
+
 Copyright © 2009 Hakan Senol Ensari, released under the MIT license

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 0
 :minor: 1
-:patch: 0
+:patch: 1

data/lib/peddler/client.rb

@@ -23,15 +23,15 @@ module Peddler
       self.transport.password = password
     end
     
-    # Sets Amazon region. Works with [ "us", "uk", "de", "ca", "fr", "jp" ].
+    # Sets Amazon region.
+    #
+    # Possible regions: ["us", "uk", "de", "ca", "fr", "jp"]
     def region=(region)
       self.transport.region = region
     end
     
     # Creates an inventory batch.
     #
-    # A sample workflow:
-    #
     #    batch = client.new_inventory_batch
     #    book = new_inventory_item(
     #      :product_id => "1234567890",
@@ -40,16 +40,9 @@ module Peddler
     #      :quantity   => 1)
     #    batch << book
     #    batch.upload
-    #
-    # The batch should now have an upload id assigned to it by Amazon. Once processed, you can use this to 
-    # check the error log:
-    #
-    #     report = client.new_report :upload, :id => batch.id
-    #     report.body
-    #
-    # That should output something like the following, assuming everything went well with the upload:
-    #
-    #     "Feed Processing Summary:\n\tNumber of records processed\t\t1\n\tNumber of records successful\t\t1\n\n"
+    #    report = client.new_report :upload, :id => batch.id
+    #    p report.body
+    #    => "Feed Processing Summary:\n\tNumber of records processed\t\t1\n\tNumber of records successful\t\t1\n\n"
     #
     def new_inventory_batch
       Peddler::Inventory::Batch.new(self.transport.dup)
@@ -68,8 +61,6 @@ module Peddler
     
     # Creates an order fulfillment batch.
     #
-    # A sample workflow:
-    #
     #    feed = client.new_order_fulfillment_feed
     #    fulfilled_order = new_fulfilled_order(
     #      :order_id    => "123-1234567-1234567",
@@ -78,15 +69,10 @@ module Peddler
     #    feed.upload
     #    feed.status
     #    => "_SUBMITTED_"
-    #
-    # Now, refresh the status until you see:
-    #
+    #    sleep(60)
     #    feed.status!
     #    => "_DONE_"
-    #
-    # Finally, check the processing report:
-    #
-    #    feed.download.to_s
+    #    p feed.download.to_s
     #
     def new_order_fulfillment_feed
       Peddler::Feeds::OrderFulfillment::Batch.new(self.transport.dup)
@@ -100,24 +86,19 @@ module Peddler
     
     # Creates an order cancellation batch.
     #
-    # A sample workflow:
-    #
     #    feed = client.new_order_cancellation_feed
     #    cancelled_order = new_cancelled_order(
-    #      :order_id    => "123-1234567-1234567")
+    #      :order_id    => "123-1234567-1234567",
+    #      :cancellation_reason_code => "NoInventory",
+		#      :amazon_order_item_code => "12341234567890")
     #    feed << cancelled_order
     #    feed.upload
     #    feed.status
     #    => "_SUBMITTED_"
-    #
-    # Now, refresh the status until you see:
-    #
+    #    sleep(60)
     #    feed.status!
     #    => "_DONE_"
-    #
-    # Finally, check the processing report:
-    #
-    #    feed.download.to_s
+    #    p feed.download.to_s
     #
     def new_order_cancellation_feed
       Peddler::Feeds::OrderCancellation::Batch.new(self.transport.dup)
@@ -140,17 +121,13 @@ module Peddler
     #      :message                  => "With our apologies.")
     #    batch << refund
     #    batch.upload
-    #
-    # To follow up on the status of the upload a little while afterwards:
-    #
+    #    sleep(60)
     #    status = client.latest_reports :batch_refund, :count => 1
     #    report = client.new_report(
     #      :batch_refund,
     #      :id => status[0].id)
-    #   
-    # Assuming the refund was successfully processed, report.body should now output:
-    #
-    #    "123-1234567-1234567order-item-id: 12341234567890\tSUCCESS 10.00 is Refunded.\r\n"
+    #    p report.body
+    #    => "123-1234567-1234567order-item-id: 12341234567890\tSUCCESS 10.00 is Refunded.\r\n"
     #
     def new_refund_batch
       Peddler::Refunds::Batch.new(self.transport.dup)
@@ -158,19 +135,21 @@ module Peddler
     
     # Creates a refund item that can then be added to a refund batch.
     #
-    # Reasons can be [ "GeneralAdjustment" "CouldNotShip" "DifferentItem" "MerchandiseNotReceived" "MerchandiseNotAsDescribed" ].
+    # Possible reasons: ["GeneralAdjustment", "CouldNotShip", "DifferentItem", "MerchandiseNotReceived", "MerchandiseNotAsDescribed"]
     def new_refund(params={})
       Peddler::Refunds::Item.new(params)
     end
     
     # Creates an instance for an already-generated report. Works only with what I call legacy reports, that is,
-    # anything that comes before section 7 in the API docs. Report names can be [ :upload, :order, :preorder, :batch_refund, :open_listings, :open_listings_lite, :open_listings_liter ].
+    # anything that comes before section 7 in the API docs.
+    #
+    # Possible report names: [:upload, :order, :preorder, :batch_refund, :open_listings, :open_listings_lite, :open_listings_liter]
     #
     # You can download a specific report by using its ID. Otherwise, the instance will fetch the latest available report. One
     # oddball exception: upload reports do require an ID and will return nil if you don't provide one.
     # 
     #    orders_report = client.new_report :order
-    #    orders = Peddler::Handlers::TabDelimitedHandler.decode_response(orders_report.body)
+    #    orders = client.detab(orders_report.body)
     #    orders[0].buyer_name
     #    => "John Doe"
     #
@@ -178,7 +157,7 @@ module Peddler
     #      :preorder,
     #      :product_line  => "Books",
     #      :frequency     => 2)
-    #    preorders = Peddler::Handlers::TabDelimitedHandler.decode_response(preorders_report.body)
+    #    preorders = client.detab(preorders_report.body)
     #    preorders[0].average_asking_price
     #    => "100"
     # 
@@ -186,14 +165,12 @@ module Peddler
       Peddler::LegacyReports::Report.new(self.transport.dup, name, params)
     end
     
-    # Requests a report. Returns true when successful. Name can be [ :order, :open_listings, :open_listings_lite, :open_listings_liter ].
+    # Requests a report. Returns true when successful.
     #
-    # Here's some sample usage:
+    # Possible report names: [:order, :open_listings, :open_listings_lite, :open_listings_liter]
     #
     #    client.generate_report :order, :number_of_days => 15
     #
-    #    client.generate_report :open_listings
-    #
     # A word of caution. Open listings may crap up with larger inventories. I will have to migrate to a cURL-based
     # HTTP client to get that working again.
     def generate_report(name,params={})
@@ -206,15 +183,10 @@ module Peddler
     #    report = client.new_unshipped_order_report
     #    report.status
     #    => "_SUBMITTED_"
-    #
-    # Now, refresh the status until you see:
-    #
+    #    sleep(60)
     #    report.status!
     #    => "_DONE_"
-    #
-    # Once done, you'll get a nifty array of unshipped orders:
-    #
-    #    report.unshipped_orders
+    #    p report.unshipped_orders
     #   
     def new_unshipped_orders_report(params={})
       Peddler::Reports::UnshippedOrdersReport.new(self.transport.dup, params)
@@ -222,8 +194,6 @@ module Peddler
     
     # Returns status of most recent reports. Optional "count" defaults to 10. Name can be [ :upload, :order, :batch_refund, :open_listings, :open_listings_lite, :open_listings_liter ].
     #
-    # Some sample usage:
-    #
     #    reports = client.latest_reports :order, :count => 1
     #    reports[0]
     #    => #<Peddler::LegacyReports::ReportStatus starts_at="07-29-2009:10-00-06" ... 
@@ -232,6 +202,11 @@ module Peddler
       Peddler::LegacyReports.latest(self.transport, name, params)
     end
     
+    # Decodes tab-delimited content into an array of OpenStruct objects.
+    def detab(msg)
+      Peddler::Handlers::TabDelimitedHandler.decode_response(msg)
+    end
+    
   protected
     def transport #:nodoc:all
       @transport ||= Peddler::Transport.new

data/lib/peddler/feeds.rb

@@ -173,6 +173,9 @@ module Peddler
         
         # Outputs a formatted line for the tab-delimited upload file.
         def to_s
+          if @cancellation_reason_code.nil? != @amazon_order_item_code.nil?
+            raise PeddlerError.new("Provide codes for both cancellation reason and Amazon order item (or omit both).")
+          end
           "#{@order_id}\t#{@cancellation_reason_code}\t#{@amazon_order_item_code}\r\n"
         end
       end

data/lib/peddler/handlers.rb

@@ -38,7 +38,7 @@ module Peddler
     end
     
     class TabDelimitedHandler
-      # Parses tab-delimited content, returning an array of OpenStruct objects corresponding to the rows in the former.
+      # Decodes tab-delimited content into an array of OpenStruct objects.
       def self.decode_response(res)
         lines = res.split("\n")
         if lines.size > 1

data/peddler.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{peddler}
-  s.version = "0.1.0"
+  s.version = "0.1.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Hakan Senol Ensari"]

data/spec/peddler/feeds_spec.rb

@@ -64,6 +64,16 @@ module Peddler
           @feed << @cancelled_order
           @feed.file_content.should == "TemplateType=OrderCancellation  Version=1.0/1.0.3 This row for Amazon.com use only.  Do not modify or delete.\r\norder-id\tcancellation-reason-code\tamazon-order-item-code\r\n123-1234567-1234567\t\t\r\n"
         end
+        
+        it "should raise error if cancellation reason code is given but Amazon order item code is missing" do
+          @cancelled_order.cancellation_reason_code = "BuyerCanceled"
+          lambda { @cancelled_order.to_s }.should raise_error(PeddlerError)
+        end
+        
+        it "should raise error if Amazon order item code is given but cancellation reason code is missing" do
+          @cancelled_order.amazon_order_item_code = "111111111111"
+          lambda { @cancelled_order.to_s }.should raise_error(PeddlerError)
+        end
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: snl-peddler
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Hakan Senol Ensari