peddler 0.3.1 → 0.4.1

data/LICENSE

@@ -1,10 +1,10 @@
 (The MIT License)
 
-Copyright (c) 2009-2010 Paper Cavalier
+Copyright (c) 2012 Paper Cavalier
 
 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
+"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
@@ -13,7 +13,7 @@ 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,
+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

data/README.md

@@ -1,128 +1,65 @@
-Peddler
-=======
+# Peddler
 
-Peddler is a Ruby wrapper to the Amazon Inventory management API.
+[![travis][1]][2]
 
-![Peddler](http://github.com/papercavalier/peddler/raw/master/mussels.jpg)
+![Peddler][3]
 
-Example usage
--------------
+Peddler wraps the [Amazon Marketplace Web Service (MWS) APIs][4].
 
-Set up a client:
+```ruby
+service = Peddler.new 'US'
 
-    client = Peddler::Client.new(
-      :username => 'foo@bar.com',
-      :password => 'secret',
-      :region   => :us)
+service.configure key:    'key',
+                  secret: 'secret',
+                  seller: 'seller'
 
-Create an inventory file:
+service.status # => "GREEN"
+```
 
-    batch = client.new_inventory_batch
-    item = client.new_inventory_item(
-      :product_id => '1234567890',
-      :price      => 100.00,
-      :sku        => 'SKU-123',
-      :quantity   => 10)
-    batch << item
+## Feeds
 
-Repeat ad infinitum and upload:
+The Feeds API lets you upload inventory and order data to Amazon.
 
-    batch.upload
+## Fulfillment Inbound Shipment
 
-The batch now should have an upload ID. Now, check the error log:
+With the Fulfillment Inbound Shipment API, you can create and update inbound
+shipments of inventory in the Amazon Fulfillment Network. You can also request
+lists of inbound shipments or inbound shipment items based on criteria that you
+specify.
 
-    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"
+## Fulfillment Inventory
 
-You are wondering if you have any new orders:
+The Fulfillment Inventory API lets you see what is available in your inventory.
+It's a real-time reporting mechanism that returns your current or
+recently-changed inventory supply in the Amazon fulfillment network.
 
-    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"
+## Fulfillment Outbound Shipment
 
-After processing the orders, post back the results to Amazon:
+The Fulfillment Outbound Shipment API is designed to help you integrate
+Fulfillment by Amazon with any payment processing application or inventory
+management system currently in use.
 
-    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
+## Orders
 
-Once done, upload:
+The Orders API helps you build simple applications that retrieve only the order
+information that you need.
 
-    feed.upload
+## Products
 
-Want to see the processing report?
+The Products API helps you get information to match your products to existing
+product listings on Amazon Marketplace websites and to make sourcing and
+pricing decisions for listing those products on Amazon Marketplace websites.
 
-    p feed.status
-    => "_SUBMITTED_"
+## Reports
 
-Refresh until you get:
+The Reports API lets you request reports about your inventory and orders.
 
-    p feed.status!
-    => "_DONE_"
+## Sellers
 
-Then, check the report:
+The Sellers API lets sellers retrieve information about their seller account,
+such as the marketplaces they participate in.
 
-    p feed.download.to_s
-
-You have an order you can't fill and haven't shipped yet. No problem:
-
-    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
-    => ...
-
-To post a refund for an already-shipped item, you use the batch refund 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
-
-For a change, let's download something different from Amazon, like 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"
-
-[Read source](http://gloss.papercavalier.com/peddler) for more info.
-
-Todo
-----
-
-Switch to using the [Amazon Marketplace Web Service (Amazon MWS)](https://mws.amazon.com/index.html).
-
-Compatibility
--------------
-
-Specs pass against Ruby 1.8.7, Ruby 1.9.2, and Rubinius 1.1.
+[1]: https://secure.travis-ci.org/papercavalier/peddler.png
+[2]: http://travis-ci.org/papercavalier/peddler
+[3]: http://f.cl.ly/items/0W3V0A1Z110Q0x461b3H/mussels.jpeg
+[4]: https://developer.amazonservices.com/gp/mws/docs.html

data/lib/peddler/feeds.rb

@@ -1,187 +1,7 @@
-module Peddler
-
-  # This module includes functionality to handle the charge-when-ship-related 
-  # feeds Amazon added to the API in 2009.
-  module Feeds
-
-    # This is a downloadable file. Outputs Amazon's response verbatim for now.
-    class Download
-      attr_accessor :id, :type, :related_reference_id, :available_at, :acknowledged
-
-      MAPPED_PARAMS = {
-        'DownloadId'          => 'id',
-        'DownloadType'        => 'type',
-        'RelatedReferenceId'  => 'related_reference_id',
-        'AvailableDate'       => 'available_at',
-        'Acknowledged'        => 'acknowledged'}
-
-      def initialize(transport, params={})
-        @transport = transport
-        params.each_pair{ |k, v| self.send "#{MAPPED_PARAMS[k]}=", v }
-      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
-
-      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'}
-
-      def initialize(transport)
-        @transport = transport
-        @batch = []
-      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
+require 'peddler/service'
 
-      # 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)
-        upload = Hash.from_xml(res)['Response']['Upload'] || Hash.from_xml(res)['Response']['UploadsStatusList']['Upload']
-        upload.each_pair do |key, value|
-          if key == 'RelatedDownloadsList'
-            @download = Peddler::Feeds::Download.new(@transport, value['Download'])
-          else
-            self.send "#{MAPPED_PARAMS[key]}=", value
-          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
+module Peddler
+  # The Feeds API lets you upload inventory and order data to Amazon.
+  class Feeds < Service
   end
 end

data/lib/peddler/fulfillment_inbound_shipment.rb

@@ -0,0 +1,11 @@
+require 'peddler/service'
+
+# With the Fulfillment Inbound Shipment API, you can create and update inbound
+# shipments of inventory in the Amazon Fulfillment Network. You can also
+# request lists of inbound shipments or inbound shipment items based on
+# criteria that you specify.
+module Peddler
+  class FulfillmentInboundShipment < Service
+    path 'FulfillmentInboundShipment/2010-10-01'
+  end
+end

data/lib/peddler/fulfillment_inventory.rb

@@ -0,0 +1,10 @@
+require 'peddler/service'
+
+module Peddler
+  # The Fulfillment Inventory API lets you see what is available in your
+  # inventory. It's a real-time reporting mechanism that returns your current
+  # or recently-changed inventory supply in the Amazon fulfillment network.
+  class FulfillmentInventory < Service
+    path 'FulfillmentInventory/2010-10-01'
+  end
+end

data/lib/peddler/fulfillment_outbound_shipment.rb

@@ -0,0 +1,10 @@
+require 'peddler/service'
+
+module Peddler
+  # The Fulfillment Outbound Shipment API is designed to help you integrate
+  # Fulfillment by Amazon with any payment processing application or inventory
+  # management system currently in use.
+  class FulfillmentOutboundShipment < Service
+    path 'FulfillmentOutboundShipment/2010-10-01'
+  end
+end

data/lib/peddler/orders.rb

@@ -0,0 +1,10 @@
+require 'peddler/service'
+
+module Peddler
+  # The Orders API helps you build simple applications that retrieve only the
+  # order information that you need.
+  class Orders < Service
+    path 'Orders/2011-01-01'
+  end
+end
+

data/lib/peddler/products.rb

@@ -0,0 +1,11 @@
+require 'peddler/service'
+
+module Peddler
+  # The Products API helps you get information to match your products to
+  # existing product listings on Amazon Marketplace websites and to make
+  # sourcing and pricing decisions for listing those products on Amazon
+  # Marketplace websites.
+  class Products < Service
+    path 'Products/2011-10-01'
+  end
+end

data/lib/peddler/reports.rb

@@ -1,97 +1,7 @@
-module Peddler
-
-  # This module generates and downloads unshipped order reports.
-  # I decided to keep this out of Peddler::LegacyReports because the API is
-  # quite different.
-  module Reports
-
-    # This is an unshipped orders report. It is very similar to the feed 
-    # objects, so I'm just porting over the class.
-    class UnshippedOrdersReport < Peddler::Feeds::Feed
-      alias         :unshipped_orders :batch
-      attr_accessor :starts_at, :ends_at, :scheduled
-
-      MAPPED_PARAMS = {
-        'ReportID'                  => 'id',
-        'StartDate'                 => 'starts_at',
-        'EndDate'                   => 'ends_at',
-        'DownloadType'              => 'type',
-        'Scheduled'                 => 'scheduled',
-        'ReportStatus'              => 'status',
-        'SubmittedDate'             => 'submitted_at',
-        'StartedProcessingDate'     => 'started_processing_at',
-        'CompletedProcessingDate'   => 'completed_processing_at',
-        'CompletedProcesssingDate'  => 'completed_processing_at'}
-
-      # Creates new unshipped order report. It will send a request to 
-      # Amazon to generate the report if the report ID is not already set.
-      def initialize(transport, params={})
-        super(transport)
-        params.each_pair{ |key, value| self.send "#{key}=", value }
-        @starts_at ||= (Date.today - 7).strftime("%Y-%m-%dT00:00:00-00:00")
-        @ends_at ||= (Date.today + 1).strftime("%Y-%m-%dT00:00:00-00:00")
-        #@type ||= "_GET_CONVERGED_FLAT_FILE_ACTIONABLE_ORDER_DATA_"
-        @type ||= "_GET_FLAT_FILE_ACTIONABLE_ORDER_DATA_"
-        if @id.nil?
-          generate_report
-        end
-        self
-      end
-
-      private
-
-      def refresh_status
-        @transport.modernize_request
-        @transport.query_params.merge!({
-          "Action"   => "reportStatus",
-          "reportId" => @id})
-        res = @transport.execute_request
-        process_response(res)
-      end
+require 'peddler/service'
 
-      def generate_report
-        @transport.modernize_request
-        @transport.query_params.merge!({
-          'Action'       => 'generateReport',
-          'startDate'    => @starts_at,
-          'endDate'      => @ends_at,
-          'downloadType' => @type})
-        res = @transport.execute_request
-        process_response(res)
-      end
-
-      def process_response(res)
-        hash = Hash.from_xml(res)
-        report = Hash.from_xml(res)['Response']['Report'] || Hash.from_xml(res)['Response']['ReportsList']['Report']
-        report.each_pair do |key, value|
-          if key == "ListOfDownloads"
-            @download = Peddler::Feeds::Download.new(@transport, value['Download'])
-            @batch = Peddler::Handlers::TabDelimitedHandler.decode_response(@download.to_s)
-          else
-            self.send "#{MAPPED_PARAMS[key]}=", value
-          end
-        end
-      end
-    end
-
-    # This is an unshipped order.
-    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
+module Peddler
+  # The Reports API lets you request reports about your inventory and orders.
+  class Reports < Service
   end
 end

data/lib/peddler/sellers.rb

@@ -0,0 +1,9 @@
+require 'peddler/service'
+
+module Peddler
+  # The Sellers API lets sellers retrieve information about their seller
+  # account, such as the marketplaces they participate in.
+  class Sellers < Service
+    path 'Sellers/2011-07-01'
+  end
+end

data/lib/peddler/service.rb

@@ -0,0 +1,106 @@
+require 'jeff'
+
+module Peddler
+  BadLocale     = Class.new ArgumentError
+  MissingSeller = Class.new ArgumentError
+
+  # A wrapper around a Marketplace Web Services (MWS) endpoint.
+  class Service
+    include Jeff
+
+    class << self
+      # Gets/Sets the path of the MWS endpoint.
+      #
+      # path - A String path (optional).
+      def path(path = nil)
+        @path = path if path
+        @path
+      end
+    end
+
+    params 'SellerId' => -> { seller }
+
+    # A list of MWS hosts.
+    HOSTS = {
+      'CA' => 'mws.amazonservices.ca',
+      'CN' => 'mws.amazonservices.com.cn',
+      'DE' => 'mws-eu.amazonservices.com',
+      'ES' => 'mws-eu.amazonservices.com',
+      'FR' => 'mws-eu.amazonservices.com',
+      'IN' => 'mws.amazonservices.in',
+      'IT' => 'mws-eu.amazonservices.com',
+      'JP' => 'mws.amazonservices.jp',
+      'UK' => 'mws-eu.amazonservices.com',
+      'US' => 'mws.amazonservices.com'
+    }
+
+    # A list of MWS marketplace ids.
+    MARKETPLACES = {
+      'CA' => 'A2EUQ1WTGCTBG2',
+      'CN' => nil,
+      'DE' => 'A1PA6795UKMFR9',
+      'ES' => 'A1RKKUPIHCS9HS',
+      'FR' => 'A13V1IB3VIYZZH',
+      'IN' => nil,
+      'IT' => 'APJ6JRA9NG5V4',
+      'JP' => 'A1VC38T7YXB528',
+      'UK' => 'A1F83G8C2ARO7P',
+      'US' => 'ATVPDKIKX0DER'
+    }
+
+    def self.inherited(base)
+      base.params params
+    end
+
+    # Creates a new service endpoint for given locale.
+    #
+    # locale - The String MWS API locale.
+    #
+    # Raises a Bad Locale error if locale is not valid.
+    def initialize(locale)
+      @host = HOSTS[@locale = locale] or raise BadLocale
+    end
+
+    # Configures the MWS endpoint.
+    #
+    # credentials - The Hash credentials.
+    #               :key    - The String Amazon Web Services (AWS) key.
+    #               :secret - The String AWS secret.
+    #               :seller - The String MWS Seller Id.
+    #
+    # Returns nothing.
+    def configure(credentials)
+      credentials.each { |key, val| self.send "#{key}=", val }
+    end
+
+    # Returns the String MWS endpoint.
+    def endpoint
+      "https://#{@host}/#{self.class.path}"
+    end
+
+    # Returns a String Marketplace id.
+    #
+    # locale - The String MWS API locale (default: the locale of the service
+    #          endpoint).
+    def marketplace(locale = nil)
+      MARKETPLACES[locale || @locale] or raise BadLocale
+    end
+
+    # Gets the String MWS seller id.
+    #
+    # Raises a Missing Seller error if seller id is missing.
+    def seller
+      @seller or raise MissingSeller
+    end
+
+    # Sets the String MWS seller id.
+    attr_writer :seller
+
+    # Gets the String service status.
+    def status
+      get(query: { 'Action' => 'GetServiceStatus' })
+        .body
+        .match(/GREEN_?I?|YELLOW|RED/)[0]
+    end
+  end
+end

data/lib/peddler/version.rb

@@ -1,3 +1,3 @@
 module Peddler
-  VERSION = '0.3.1'
+  VERSION = '0.4.1'
 end