snl-peddler 0.1.0

data/.gitignore

@@ -0,0 +1 @@
+.DS_Store

data/History.txt

@@ -0,0 +1,2 @@
+== 0.1.0 / 2009-08-14
+  * First public release.

data/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+ 
+Copyright (c) 2009 Hakan Şenol Ensari
+ 
+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/README.rdoc

@@ -0,0 +1,104 @@
+=  Peddler
+
+Peddler is a Ruby wrapper to the Amazon Inventory management API.
+
+== Example usage
+
+Fire off a client:
+
+  client = Peddler::Client.new(
+    :username => "foo@bar.com",
+    :password => "secret",
+    :region   => "us")
+
+Create an inventory file:
+
+  batch = client.new_inventory_batch
+  item = client.new_inventory_item(
+    :product_id => "1234567890",
+    :price      => 100.00,
+    :sku        => "SKU-123",
+    :quantity   => 10)
+  batch << item
+  ...
+
+Repeat ad infinitum and then upload:
+
+  batch.upload
+
+The batch now should have an upload ID assigned to it. Let's check its 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:
+
+  orders_report = client.new_report :order
+  orders = Peddler::Handlers::TabDelimitedHandler.decode_response(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:
+  
+  feed = client.new_order_fulfillment_feed
+  fulfilled_order = new_fulfilled_order(
+    :order_id         => "123-1234567-1234567",
+    :order_date       => "2009-08-01",
+    :carrier_code     => "USPS",
+    :tracking_number  => "0308 0330 0000 0000 0000")
+  feed << fulfilled_order
+  
+Again, repeat until done and upload:
+
+  feed.upload
+  
+Curious to see the processing report?
+  
+  p feed.status
+  => "_SUBMITTED_"
+  
+Refresh until you see:
+
+  p feed.status!
+  => "_DONE_"
+
+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:
+
+  feed = client.new_order_cancellation_feed
+  cancelled_order = new_cancelled_order(
+    :order_id => "123-1234567-1234567")
+  feed << cancelled_order
+  feed.upload
+  sleep(60)
+  feed.status!
+  => "_DONE_"  
+  p feed.download.to_s
+  => ...
+
+Run rdoc and check the source for more detailed info.
+
+Copyright © 2009 Hakan Senol Ensari, released under the MIT license

data/Rakefile

@@ -0,0 +1,17 @@
+require "rubygems"
+require "rake"
+begin
+  require "jeweler"
+  Jeweler::Tasks.new do |s|
+    s.name = "peddler"
+    s.summary = "Peddler is a Ruby wrapper to the Amazon Inventory Management API."
+    s.email = "hakan.ensari@papercavalier.com"
+    s.homepage = "http://github.com/snl/peddler"
+    s.description = "Peddler is a Ruby wrapper to the Amazon Inventory Management API."
+    s.authors = ["Hakan Senol Ensari"]
+    s.add_dependency "xmlsimple"
+    s.add_development_dependency "rspec"
+  end
+rescue LoadError
+  puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end

data/VERSION.yml

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

data/lib/peddler.rb

@@ -0,0 +1,25 @@
+# Peddler is a Ruby wrapper to the Amazon Inventory management API.
+module Peddler
+  VERSION = "0.1"  
+end
+
+class String #:nodoc: all
+  def camelize
+    self.gsub(/(^|_)(.)/) { $2.upcase }
+  end
+end
+
+require "net/https"
+require "ostruct"
+require "tempfile"
+require "time"
+require "xmlsimple"
+
+require File.dirname(__FILE__) + "/peddler/client"
+require File.dirname(__FILE__) + "/peddler/handlers"
+require File.dirname(__FILE__) + "/peddler/feeds"
+require File.dirname(__FILE__) + "/peddler/inventory"
+require File.dirname(__FILE__) + "/peddler/legacy_reports"
+require File.dirname(__FILE__) + "/peddler/refunds"
+require File.dirname(__FILE__) + "/peddler/reports"
+require File.dirname(__FILE__) + "/peddler/transport"

data/lib/peddler/client.rb

@@ -0,0 +1,240 @@
+# = Peddler
+# Peddler is a Ruby wrapper to the Amazon Inventory management API.
+# 
+# Peddler::Client has some detailed explanation and examples of usage.
+module Peddler
+  # This is the public interface of the Peddler library.
+  class Client
+    # Creates a client instance.
+    #
+    #    client = Peddler::Client.new :username => "foo@bar.com",
+    #                                 :password => "secret",
+    #                                 :region => "us"
+    #
+    def initialize(params={})
+      params.each_pair { |key, value| self.send("#{key}=", value) }
+    end
+    
+    def username=(username)
+      self.transport.username = username
+    end
+    
+    def password=(password)
+      self.transport.password = password
+    end
+    
+    # Sets Amazon region. Works with [ "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",
+    #      :sku        => "SKU-001",
+    #      :price      => 10.00,
+    #      :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"
+    #
+    def new_inventory_batch
+      Peddler::Inventory::Batch.new(self.transport.dup)
+    end
+    
+    # Creates an inventory item. Parameter keys are lowercased and underscored but otherwise the same as
+    # Amazon's colum titles in their tab-delimited templates.
+    def new_inventory_item(params={})
+      Peddler::Inventory::Item.new(params)
+    end
+    
+    # Returns count of pending inventory uploads queued at Amazon.
+    def inventory_queue
+      Peddler::Inventory::Queue.count(self.transport)
+    end
+    
+    # Creates an order fulfillment batch.
+    #
+    # A sample workflow:
+    #
+    #    feed = client.new_order_fulfillment_feed
+    #    fulfilled_order = new_fulfilled_order(
+    #      :order_id    => "123-1234567-1234567",
+    #      :order_date  => "2009-08-01")
+    #    feed << fulfilled_order
+    #    feed.upload
+    #    feed.status
+    #    => "_SUBMITTED_"
+    #
+    # Now, refresh the status until you see:
+    #
+    #    feed.status!
+    #    => "_DONE_"
+    #
+    # Finally, check the processing report:
+    #
+    #    feed.download.to_s
+    #
+    def new_order_fulfillment_feed
+      Peddler::Feeds::OrderFulfillment::Batch.new(self.transport.dup)
+    end
+    
+    # Creates an item that can then be added to an order fulfillment feed. Keys are lowercased and underscored but
+    # otherwise the same as Amazon's headers. See section 7.1 in the API docs.
+    def new_fulfilled_order(params={})
+      Peddler::Feeds::OrderFulfillment::Item.new(params)
+    end
+    
+    # Creates an order cancellation batch.
+    #
+    # A sample workflow:
+    #
+    #    feed = client.new_order_cancellation_feed
+    #    cancelled_order = new_cancelled_order(
+    #      :order_id    => "123-1234567-1234567")
+    #    feed << cancelled_order
+    #    feed.upload
+    #    feed.status
+    #    => "_SUBMITTED_"
+    #
+    # Now, refresh the status until you see:
+    #
+    #    feed.status!
+    #    => "_DONE_"
+    #
+    # Finally, check the processing report:
+    #
+    #    feed.download.to_s
+    #
+    def new_order_cancellation_feed
+      Peddler::Feeds::OrderCancellation::Batch.new(self.transport.dup)
+    end
+    
+    # Creates an item that can then be added to an order cancellation feed. Keys are lowercased and underscored but
+    # otherwise the same as Amazon's headers. See section 7.4 in the API docs.
+    def new_cancelled_order(params={})
+      Peddler::Feeds::OrderCancellation::Item.new(params)
+    end
+    
+    # Creates a refund batch.
+    #
+    #    batch = client.new_refund_batch
+    #    refund = client.new_refund(
+    #      :order_id                 => "123-1234567-1234567",
+    #      :payments_transaction_id  => "12341234567890",
+    #      :refund_amount            => 10.00,
+    #      :reason                   => "CouldNotShip",
+    #      :message                  => "With our apologies.")
+    #    batch << refund
+    #    batch.upload
+    #
+    # To follow up on the status of the upload a little while afterwards:
+    #
+    #    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"
+    #
+    def new_refund_batch
+      Peddler::Refunds::Batch.new(self.transport.dup)
+    end
+    
+    # Creates a refund item that can then be added to a refund batch.
+    #
+    # Reasons can be [ "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 ].
+    #
+    # 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[0].buyer_name
+    #    => "John Doe"
+    #
+    #    preorders_report = client.new_report(
+    #      :preorder,
+    #      :product_line  => "Books",
+    #      :frequency     => 2)
+    #    preorders = Peddler::Handlers::TabDelimitedHandler.decode_response(preorders_report.body)
+    #    preorders[0].average_asking_price
+    #    => "100"
+    # 
+    def new_report(name,params={})
+      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 ].
+    #
+    # Here's some sample usage:
+    #
+    #    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={})
+      Peddler::LegacyReports.generate(self.transport, name, params)
+    end
+    
+    # Creates an unshipped order report. Takes on some optional parameters, such as :id, :starts_at, :ends_at. By default,
+    # it will request a new unshipped order report for the past seven days.
+    #
+    #    report = client.new_unshipped_order_report
+    #    report.status
+    #    => "_SUBMITTED_"
+    #
+    # Now, refresh the status until you see:
+    #
+    #    report.status!
+    #    => "_DONE_"
+    #
+    # Once done, you'll get a nifty array of unshipped orders:
+    #
+    #    report.unshipped_orders
+    #   
+    def new_unshipped_orders_report(params={})
+      Peddler::Reports::UnshippedOrdersReport.new(self.transport.dup, params)
+    end
+    
+    # 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" ... 
+    #
+    def latest_reports(name,params={})
+      Peddler::LegacyReports.latest(self.transport, name, params)
+    end
+    
+  protected
+    def transport #:nodoc:all
+      @transport ||= Peddler::Transport.new
+    end
+  end
+end

data/lib/peddler/feeds.rb

@@ -0,0 +1,181 @@
+module Peddler
+  # This module includes functionality to handle the charge-when-ship-related feeds Amazon added to the API
+  # in its latest incarnation in 2009.
+  module Feeds
+    # Downloadable file. The processing report in case of feeds. Outputs Amazon's response verbatim.
+    # Will add functionality to parse the response some time down the road.
+    class Download
+      attr_accessor :id, :type, :related_reference_id, :available_at, :acknowledged
+      
+      def initialize(transport, params={})
+        @mapped_params = {
+          "DownloadId"          => "id",
+          "DownloadType"        => "type",
+          "RelatedReferenceId"  => "related_reference_id",
+          "AvailableDate"       => "available_at",
+          "Acknowledged"        => "acknowledged"}
+        @transport = transport
+        params.each_pair{ |key, value| self.send "#{@mapped_params[key]}=", value }
+      end
+      
+      # Retrieves and returns report
+      def to_s
+        @body ||= download_report
+      end
+    private
+      def download_report
+        return nil if @id.nil?
+        @transport.modernize_request
+        @transport.query_params.merge!({
+          "Action"      => "download",
+          "downloadId"  => @id})
+        @transport.execute_request
+      end
+    end
+    
+    # This is the base class.
+    class Feed
+      attr_writer   :file_content
+      attr_accessor :batch, :download, :status, :type, :id, :submitted_at, :started_processing_at, :completed_processing_at, :messages_processed, :messages_successful, :messages_with_errors, :messages_with_warnings
+      
+      def initialize(transport)
+        @transport = transport
+        @batch = []
+        @mapped_params = {
+          "UploadStatus"              => "status",
+          "UploadType"                => "type",
+          "UploadId"                  => "id",
+          "SubmittedDate"             => "submitted_at",
+          "StartedProcessingDate"     => "started_processing_at",
+          "CompletedProcessingDate"   => "completed_processing_at",
+          "CompletedProcesssingDate"  => "completed_processing_at",
+          "MessagesProcessed"         => "messages_processed",
+          "MessagesSuccessful"        => "messages_successful",
+          "MessagesWithErrors"        => "messages_with_errors",
+          "MessagesWithWarnings"      => "messages_with_warnings"}
+      end
+      
+      # Returns content of the upload file.
+      def file_content
+        return @file_content if @file_content 
+        out = @file_header
+        @batch.each{ |item| out << item.to_s }
+        @file_content = out
+      end
+      
+      # Returns status and will also refresh if not already "done."
+      def status!
+        return @status if @status.nil? || @status =~ /_DONE_/
+        refresh_status
+        @status
+      end
+      
+      # Uploads batch.
+      def upload
+        raise PeddlerError.new("Batch already uploaded") unless @id.nil?
+        @transport.modernize_request
+        @transport.query_params.merge!({
+          "Action"     => "upload",
+          "uploadType" => @type})
+        @transport.body = file_content
+        res = @transport.execute_request
+        process_response(res)
+        @status
+      end
+      
+      # Adds an item to the batch.
+      def <<(item)
+        @batch << item
+      end
+    private
+      def refresh_status
+        @transport.modernize_request
+        @transport.query_params.merge!({
+          "Action"   => "uploadStatus",
+          "uploadId" => @id})
+        res = @transport.execute_request
+        process_response(res)
+      end
+      
+      def process_response(res)
+        xml = Peddler::Handlers::XMLHandler.decode_response(res)
+        params = Peddler::Handlers::XMLHandler.parse(:upload, xml)
+        if params[0]
+          params[0].each_pair do |key, value|
+            if key == "RelatedDownloadsList"
+              params = Peddler::Handlers::XMLHandler.parse(:download, value)
+              @download = Peddler::Feeds::Download.new(@transport, params[0])
+            else
+              self.send "#{@mapped_params[key]}=", value
+            end
+          end
+        end
+      end
+    end
+    
+    module OrderFulfillment
+      # This class contains methods to upload order fulfillment info to Amazon.
+      # See sections 7.1 through 7.3 in the API documentation for more detail.
+      class Batch < Peddler::Feeds::Feed
+        def initialize(transport)
+          @file_header = "order-id\torder-item-id\tquantity\tship-date\tcarrier-code\tcarrier-name\ttracking-number\tship-method\r\n"
+          @type = "_POST_FLAT_FILE_FULFILLMENT_DATA_"
+          super(transport)
+        end
+      end
+      
+      # This is an order fulfillment item.
+      class Item
+        attr_accessor :order_id, :order_item_id, :quantity, :ship_date, :carrier_name, :tracking_number, :ship_method
+        attr_reader   :carrier_code
+
+        def initialize(params={})
+          params.each_pair{ |key, value| send("#{key}=", value) }
+        end
+        
+        # Validates when setting carrier code.
+        def carrier_code=(carrier_code)
+          @carrier_code = carrier_code if %w{USPS UPS FedEx other}.include?(carrier_code)
+        end
+        
+        # Outputs a formatted line for the tab-delimited upload file.
+        def to_s
+          "#{@order_id}\t#{@order_item_id}\t#{@quantity}\t#{@ship_date}\t#{@carrier_code}\t#{@carrier_name}\t#{@tracking_number}\t#{@ship_method}\r\n"
+        end
+      end
+    end
+    
+    # This module contains methods to upload cancelled orders to Amazon.
+    # See section 7.4 in the API documentation for more detail.
+    module OrderCancellation
+      class Batch < Peddler::Feeds::Feed
+        def initialize(transport)
+          @file_header = "TemplateType=OrderCancellation  Version=1.0/1.0.3 This row for Amazon.com use only.  Do not modify or delete.\r\n" +
+                         "order-id\tcancellation-reason-code\tamazon-order-item-code\r\n"
+          @type = "_POST_FLAT_FILE_ORDER_ACKNOWLEDGEMENT_DATA_"
+          super(transport)
+        end
+      end
+
+      # This is a cancelled order item.
+      class Item
+        attr_accessor :order_id, :amazon_order_item_code
+        attr_reader   :cancellation_reason_code
+        
+        def initialize(params={})
+          params.each_pair{ |key, value| send("#{key}=", value) }
+        end
+        
+        # Validates when setting cancellation reason code.
+        def cancellation_reason_code=(cancellation_reason_code)
+          @cancellation_reason_code = cancellation_reason_code if %w{ BuyerCanceled CustomerExchange CustomerReturn GeneralAdjustment MerchandiseNotReceived NoInventory ShippingAddressUndeliverable }.include?(cancellation_reason_code)
+        end
+        
+        # Outputs a formatted line for the tab-delimited upload file.
+        def to_s
+          "#{@order_id}\t#{@cancellation_reason_code}\t#{@amazon_order_item_code}\r\n"
+        end
+      end
+    end
+  end
+end