peddler 0.1.3

data/.gitignore

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

data/History.txt

@@ -0,0 +1,8 @@
+== 0.1.0 / 2009-08-14
+  * First public release.
+== 0.1.1 / 2009-08-15
+	* Bumping gem to tag correctly on Github.
+== 0.1.2 / 2009-08-17
+	* Minor stuff.
+== 0.1.3 / 2009-11-06
+	* Nothing major, Tom.

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,118 @@
+=  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 upload:
+
+  batch.upload
+
+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 listing and are wondering if you have any new orders:
+
+  orders_report = client.new_report :order
+  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"
+
+Now that you have diligently processed the orders, post back the results to Amazon:
+  
+  feed = client.new_order_fulfillment_feed
+  fulfilled_order = client.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 get:
+
+  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 similar:
+
+  feed = client.new_order_cancellation_feed
+  cancelled_order = client.new_cancelled_order(
+    :order_id => "123-1234567-1234567",
+    :cancellation_reason_code => "NoInventory",
+    :amazon_order_item_code => "12341234567890")
+  feed << cancelled_order
+  feed.upload
+  sleep(60)
+  feed.status!
+  => "_DONE_"  
+  p feed.download.to_s
+  => ...
+
+Need to post a partial refund? You'll have to revert to the older batch refund API method:
+
+  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.
+
+Copyright © 2009 Hakan Senol Ensari, released under the MIT license

data/Rakefile

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

data/VERSION.yml

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

data/init.rb

@@ -0,0 +1 @@
+require 'peddler'

data/lib/peddler/client.rb

@@ -0,0 +1,215 @@
+# = 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.
+    #
+    # Possible regions: ["us", "uk", "de", "ca", "fr", "jp"]
+    def region=(region)
+      self.transport.region = region
+    end
+    
+    # Creates an inventory batch.
+    #
+    #    batch = client.new_inventory_batch
+    #    book = new_inventory_item(
+    #      :product_id => "1234567890",
+    #      :sku        => "SKU-001",
+    #      :price      => 10.00,
+    #      :quantity   => 1)
+    #    batch << book
+    #    batch.upload
+    #    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)
+    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.
+    #
+    #    feed = client.new_order_fulfillment_feed
+    #    fulfilled_order = client.new_fulfilled_order(
+    #      :order_id    => "123-1234567-1234567",
+    #      :order_date  => "2009-08-01")
+    #    feed << fulfilled_order
+    #    feed.upload
+    #    feed.status
+    #    => "_SUBMITTED_"
+    #    sleep(60)
+    #    feed.status!
+    #    => "_DONE_"
+    #    p 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.
+    #
+    #    feed = client.new_order_cancellation_feed
+    #    cancelled_order = client.new_cancelled_order(
+    #      :order_id    => "123-1234567-1234567",
+    #      :cancellation_reason_code => "NoInventory",
+		#      :amazon_order_item_code => "12341234567890")
+    #    feed << cancelled_order
+    #    feed.upload
+    #    feed.status
+    #    => "_SUBMITTED_"
+    #    sleep(60)
+    #    feed.status!
+    #    => "_DONE_"
+    #    p 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
+    #    sleep(60)
+    #    status = client.latest_reports :batch_refund, :count => 1
+    #    report = client.new_report(
+    #      :batch_refund,
+    #      :id => status[0].id)
+    #    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)
+    end
+    
+    # Creates a refund item that can then be added to a refund batch.
+    #
+    # 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.
+    #
+    # 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 = client.detab(orders_report.body)
+    #    orders[0].buyer_name
+    #    => "John Doe"
+    #
+    #    preorders_report = client.new_report(
+    #      :preorder,
+    #      :product_line  => "Books",
+    #      :frequency     => 2)
+    #    preorders = client.detab(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.
+    #
+    # Possible report names: [:order, :open_listings, :open_listings_lite, :open_listings_liter]
+    #
+    #    client.generate_report :order, :number_of_days => 15
+    #
+    # 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_orders_report
+    #    report.status
+    #    => "_SUBMITTED_"
+    #    sleep(60)
+    #    report.status!
+    #    => "_DONE_"
+    #    p 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 ].
+    #
+    #    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
+    
+    # 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
+    end
+  end
+end

data/lib/peddler/feeds.rb

@@ -0,0 +1,184 @@
+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
+          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
+    end
+  end
+end

data/lib/peddler/handlers.rb

@@ -0,0 +1,58 @@
+module Peddler
+  module Handlers
+    class XMLHandler
+      # Decodes an XML response.
+      def self.decode_response(res)
+        XmlSimple.xml_in(res)
+      end
+      # Parses responses to uploads and status queries for feeds in Section 7 of the docs. Walks
+      # through lists and returns an array of hashes.
+      def self.parse(name, xml)
+        name = name.to_s.capitalize
+        list = xml["#{name}sStatusList"] || xml["#{name}sList"]
+        if list
+          list.collect { |s| parse_status(name, s) }
+        else
+          [ parse_status(name, xml) ]
+        end
+      end
+      
+      # Parses legacy responses to queries on statuses of generated reports and inventory uploads.
+      def self.parse_legacy(xml)
+        if xml["Batch"]
+          xml["Batch"].collect  { |input| Peddler::LegacyReports::UploadStatus.new(input) }
+        elsif xml["Report"]
+          xml["Report"].collect { |input| Peddler::LegacyReports::ReportStatus.new(input) }
+        end
+      end
+    protected
+      def self.parse_status(name, xml)
+        if xml[name]
+          xml[name][0].inject({}) do |memo, pair|
+            key, value = pair
+            value[0] = Time.parse(value[0]) if key =~ /Date$/
+            memo.merge!({ key => value[0] })
+          end
+        end
+      end
+    end
+    
+    class TabDelimitedHandler
+      # Decodes tab-delimited content into an array of OpenStruct objects.
+      def self.decode_response(res)
+        lines = res.split("\n")
+        if lines.size > 1
+          params = lines[0].split("\t").collect{ |value| value.gsub(/-/, "_") }
+          params_size = params.size
+          (1..(lines.size - 1)).collect do |line_key|
+            values = lines[line_key].split("\t")
+            data = (0..(params_size - 1)).inject({}) { |memo, key| memo.merge( { params[key] => values[key] } ) }
+            OpenStruct.new(data)
+          end
+        else
+          res
+        end
+      end
+    end
+  end
+end