peddler 0.12.7 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 30436cbe660437bbf9bd37c50f71e97cd5ea3dba
-  data.tar.gz: daf21940a611131fb3fe34a12d4bad5d25fabca1
+  metadata.gz: 9dd9c5afba95ac1d338faf962febf957b9b0c379
+  data.tar.gz: adf4cd38b3f060d0eb6bd192a7a8b26ccfb975c7
 SHA512:
-  metadata.gz: fcd83c8e7ce9ff05bacdf5344acaae8537a64fcd3f34aa43ab9e115cca5518691ce9daa07b6520ed5229f7f6b5703be7f8c4c8668865ac85ce3f33f574668be6
-  data.tar.gz: 69af1faee5272ec880e01bc835e6c88e771b44cdc6f43c6f2b549d9798dcb59d69a0a40d6427ba981bc984b22b106dfad2b9867ec64fe20f2b1dcdf06b2c33e8
+  metadata.gz: c5340b8e65c5ed04ad39da45754a61666d3585b11a190779efbe39377903a3f3b8ef495fb39d56414caae34a1a2bf93226fa2d0b40130f3c245eca050b50ea95
+  data.tar.gz: e943781a460d6302bf567e1b2c68d73ef8e151205c42350bafd909bef9e2156219a0e8d1321d91ce5e248a6e86de91aca3434ebd2a3be95f8ada00127406a122

data/README.md

@@ -7,87 +7,126 @@
 
 **Peddler** is a Ruby interface to the [Amazon MWS API](https://developer.amazonservices.com/), a collection of web services that help Amazon sellers programmatically exchange data on their listings, orders, payments, reports, and more.
 
-To use Amazon MWS, you must have an eligible seller account.
+To use Amazon MWS, you must have an eligible seller account and register for MWS. This applies to developers as well.
+
+Some MWS API sections may require additional authorisation from Amazon.
 
 ![Peddler](http://f.cl.ly/items/231z2m0r1Q2o2q1n0w1N/peddler.jpg)
 
-## Quick Start
+## Usage
+
+Require the library.
 
 ```ruby
 require 'peddler'
+```
 
+Create a client. Peddler provides one for each MWS API under an eponymous namespace.
+
+```ruby
+client = MWS::Orders::Client.new
+
+# or the shorthand
 client = MWS.orders
-parser = client.get_service_status
-parser.parse
 ```
 
-## Credentials
-
-You can set up credentials when instantiating:
+Each client requires valid MWS credentials. You can set some or all when or after creating the client.
 
 ```ruby
-client = MWS.orders(
-  marketplace_id:        "...",
-  merchant_id:           "...",
-  aws_access_key_id:     "...",
-  aws_secret_access_key: "..."
+client = MWS::Orders::Client.new(
+  marketplace_id:        "foo",
+  merchant_id:           "bar",
+  aws_access_key_id:     "baz",
+  aws_secret_access_key: "qux"
 )
+
+# Swap marketplace
+client.marketplace_id = "quux"
 ```
 
-Alternatively, use environment variables:
+Alternatively, you can set these globally in the shell.
 
 ```sh
-export MWS_MARKETPLACE_ID=...
-export MWS_MERCHANT_ID=...
-export AWS_ACCESS_KEY_ID=...
-export AWS_SECRET_ACCESS_KEY=...
+export MWS_MARKETPLACE_ID=foo
+export MWS_MERCHANT_ID=bar
+export AWS_ACCESS_KEY_ID=baz
+export AWS_SECRET_ACCESS_KEY=qux
 ```
 
-### MWS Authorized Tokens
+If you are creating a client for another seller, pass the latter's `MWSAuthToken` to the client.
 
-If instantiating a client for another seller, you have to provide the `MWSAuthToken` generated for you by the latter:
+```ruby
+client.auth_token = "corge"
+```
+
+Once you have a client with credentials, you can make requests to the API.
+
+Peddler returns the response wrapped in a simple parser that handles both XML documents and flat files.
 
 ```ruby
-client = MWS.orders(
-  marketplace_id:        "...",
-  merchant_id:           "...",
-  aws_access_key_id:     "...",
-  aws_secret_access_key: "...",
-  auth_token:            "..."
-)
+parser = client.get_service_status
+parser.parse # will return Hash or a CSV object
 ```
 
-## Usage
+You can swap the default parser with a purpose-built one.
+
+```ruby
+MWS::Orders::Client.parser = MyParser
+```
+
+For a sample implementation, see my [MWS Orders](https://github.com/hakanensari/mws-orders) library.
+
+Finally, you can handle network errors caused by throttling or other transient issues by defining an error handler.
+
+```ruby
+MWS::Orders::Client.on_error do |request, response|
+  if response.status == 503
+    logger.info "I was throttled"
+  end
+end
+```
+
+Alternatively, you can simply rescue.
+
+```ruby
+begin
+  client.some_method
+rescue Excon::Errors::ServiceUnavailable
+  sleep 1 and retry
+end
+```
+
+## The APIs
 
 ### Cart Information
 
 With the MWS Cart Information API, you can retrieve shopping carts that your Amazon Webstore customers have created. The Cart Information API enables you to programmatically integrate Amazon Webstore cart information with your CRM systems, marketing applications, and other systems that require cart data.
 
-[Read the API](http://www.rubydoc.info/gems/peddler/MWS/CartInformation/Client)
+[Read more](http://www.rubydoc.info/gems/peddler/MWS/CartInformation/Client)
 
 ### Customer Information
 
 With the MWS Customer Information API, you can retrieve information from the customer accounts of your Amazon Webstore customers. This customer information includes customer name, contact information, customer account type, and associated Amazon Webstore marketplaces. The Customer Information API enables you to programmatically integrate Amazon Webstore customer account information with your CRM systems, marketing applications, and other systems that require customer data.
 
-[Read the API](http://www.rubydoc.info/gems/peddler/MWS/CustomerInformation/Client)
+[Read more](http://www.rubydoc.info/gems/peddler/MWS/CustomerInformation/Client)
 
 ### Feeds
 
 The MWS Feeds API lets you upload inventory and order data to Amazon. You can also use this API to get information about the processing of feeds.
 
-[Read the API](http://www.rubydoc.info/gems/peddler/MWS/Feeds/Client)
+[Read more](http://www.rubydoc.info/gems/peddler/MWS/Feeds/Client)
 
 ### Fulfillment Inbound Shipment
 
 With the MWS Fulfillment Inbound Shipment API, you can create and update inbound shipments of inventory in the Amazon Fulfillment Network. You can also also request lists of inbound shipments or inbound shipment items based on criteria that you specify.
 
-[Read the API](http://www.rubydoc.info/gems/peddler/MWS/FulfillmentInboundShipment/Client)
+[Read more](http://www.rubydoc.info/gems/peddler/MWS/FulfillmentInboundShipment/Client)
 
 ### Fulfillment Inventory
 
 The MWS Fulfillment Inventory API can help you stay up-to-date on the availability of your inventory in the Amazon Fulfillment Network. The Fulfillment Inventory API reports real-time availability information for your Amazon Fulfillment Network inventory regardless of whether you are selling your inventory on Amazon's retail web site or through other retail channels.
 
-[Read the API](http://www.rubydoc.info/gems/peddler/MWS/FulfillmentInventory/Client)
+[Read more](http://www.rubydoc.info/gems/peddler/MWS/FulfillmentInventory/Client)
 
 ### Fulfillment Outbound Shipment
 
@@ -95,7 +134,7 @@ The MWS Fulfillment Outbound Shipment API enables you to fulfill orders placed t
 
 Support for creating and cancelling fulfillment orders has been implemented, but the rest of the API is not supported yet.
 
-[Read the API](http://www.rubydoc.info/gems/peddler/MWS/FulfillmentOutboundShipment/Client)
+[Read more](http://www.rubydoc.info/gems/peddler/MWS/FulfillmentOutboundShipment/Client)
 
 ### Off Amazon Payments
 
@@ -107,46 +146,46 @@ You can switch the client to the sandbox environment:
 client = MWS.off_amazon_payments.sandbox
 ```
 
-[Read the API](http://www.rubydoc.info/gems/peddler/MWS/OffAmazonPayments/Client)
+[Read more](http://www.rubydoc.info/gems/peddler/MWS/OffAmazonPayments/Client)
 
 ### Orders
 
 With the MWS Orders API, you can list orders created or updated during a time frame you specify or retrieve information about specific orders.
 
-[Read the API](http://www.rubydoc.info/gems/peddler/MWS/Orders/Client)
+[Read more](http://www.rubydoc.info/gems/peddler/MWS/Orders/Client)
 
 ### Products
 
 The MWS 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.
 
-[Read the API](http://www.rubydoc.info/gems/peddler/MWS/Products/Client)
+[Read more](http://www.rubydoc.info/gems/peddler/MWS/Products/Client)
 
 ### Recommendations
 
 The Recommendations API enables you to programmatically retrieve Amazon Selling Coach recommendations by recommendation category. A recommendation is an actionable, timely, and personalized opportunity to increase your sales and performance.
 
-[Read the API](http://www.rubydoc.info/gems/peddler/MWS/Recommendations/Client)
+[Read more](http://www.rubydoc.info/gems/peddler/MWS/Recommendations/Client)
 
 ### Reports
 
 The Reports API lets you request reports about your inventory and orders.
 
-[Read the API](http://www.rubydoc.info/gems/peddler/MWS/Reports/Client)
+[Read more](http://www.rubydoc.info/gems/peddler/MWS/Reports/Client)
 
 ### Sellers
 
 The Sellers API lets sellers retrieve information about their seller account, such as the marketplaces they participate in.
 
-[Read the API](http://www.rubydoc.info/gems/peddler/MWS/Sellers/Client)
+[Read more](http://www.rubydoc.info/gems/peddler/MWS/Sellers/Client)
 
 ### Subscriptions
 
 The Amazon MWS Subscriptions API section enables you to subscribe to receive notifications that are relevant to your business with Amazon. With the operations in the Subscriptions API section, you can register to receive important information from Amazon without having to poll the Amazon MWS service. Instead, the information is sent directly to you when an event occurs to which you are subscribed.
 
-[Read the API](http://www.rubydoc.info/gems/peddler/MWS/Subscriptions/Client)
+[Read more](http://www.rubydoc.info/gems/peddler/MWS/Subscriptions/Client)
 
 ### Webstore
 
 With the Webstore API section of Amazon Marketplace Web Service (Amazon MWS), you can get “Email Me When Available” subscription information for items listed on your Amazon Webstore. The Webstore API section can help you plan your inventory replenishment cycle by enabling you to query for items that your customers subscribed to when they clicked the Email Me When Available button on your Webstore. The Webstore API section can also return information about the notifications that were sent to your customers when out-of-stock items came back in stock. This information, when combined with sales information that your Webstore tracks, can help you determine how many notifications were converted into sales.
 
-[Read the API](http://www.rubydoc.info/gems/peddler/MWS/Webstore/Client)
+[Read more](http://www.rubydoc.info/gems/peddler/MWS/Webstore/Client)

data/lib/peddler/client.rb

@@ -23,20 +23,31 @@ module Peddler
       'MWSAuthToken' => -> { auth_token }
     )
 
-    def self.parser
-      @parser ||= Parser
-    end
+    class << self
+      attr_reader :error_handler
 
-    def self.parser=(parser)
-      @parser = parser
-    end
+      def parser
+        @parser ||= Parser
+      end
 
-    def self.path(path = nil)
-      path ? @path = path : @path ||= '/'
-    end
+      def parser=(parser)
+        @parser = parser
+      end
+
+      def path(path = nil)
+        path ? @path = path : @path ||= '/'
+      end
 
-    def self.inherited(base)
-      base.params(params)
+      def on_error(&blk)
+        @error_handler = blk
+      end
+
+      private
+
+      def inherited(base)
+        base.params(params)
+        base.on_error &@error_handler if @error_handler
+      end
     end
 
     def initialize(opts = {})
@@ -80,6 +91,10 @@ module Peddler
       @error_handler = blk
     end
 
+    def error_handler
+      @error_handler || self.class.error_handler
+    end
+
     def operation(action = nil)
       action ? @operation = Operation.new(action) : @operation
     end
@@ -90,9 +105,16 @@ module Peddler
       opts.store(:response_block, Proc.new) if block_given?
       res = post(opts)
 
-      parser.parse(res, encoding)
-    rescue Excon::Errors::Error => ex
-      handle_error(ex) or raise
+      parser.new(res, encoding)
+    rescue Excon::Errors::Error => e
+      handle_error(e) or raise
+    rescue NoMethodError => e
+      if e.message == "undefined method `new' for #{parser}"
+        warn "[DEPRECATION] `Parser.parse` is deprecated. Please use `Parser.new` instead."
+        parser.parse(res, encoding)
+      else
+        raise
+      end
     end
 
     private
@@ -117,9 +139,9 @@ module Peddler
       self.class.parser
     end
 
-    def handle_error(ex)
-      return false unless @error_handler
-      @error_handler.call(ex.request, ex.response)
+    def handle_error(e)
+      return false unless error_handler
+      error_handler.call(e.request, e.response)
     end
   end
 end

data/lib/peddler/marketplace.rb

@@ -19,7 +19,7 @@ module Peddler
     attr_reader :id
 
     def initialize(id)
-      @id = id
+      @id = id or fail BadId, 'missing MarketplaceId'
     end
 
     def host
@@ -41,7 +41,7 @@ module Peddler
     private
 
     def find_host
-      HOSTS.fetch(id) { raise BadId }
+      HOSTS.fetch(id) { fail BadId, %Q("#{id}" is not a valid MarketplaceId) }
     end
 
     def japanese?

data/lib/peddler/parser.rb

@@ -7,7 +7,7 @@ module Peddler
     class << self
       # The inevitable messiness of massaging data produced by a motley army of
       # Amazon developers
-      def parse(res, encoding = 'ISO-8859-1')
+      def new(res, encoding = 'ISO-8859-1')
         # Don't parse if there's no body
         return res unless res.body
 

data/lib/peddler/version.rb

@@ -1,3 +1,3 @@
 module Peddler
-  VERSION = '0.12.7'
+  VERSION = '0.13.0'
 end

data/test/unit/mws/test_fulfillment_inbound_shipment_client.rb

@@ -53,9 +53,11 @@ class TestMWSFulfillmentInboundShipmentClient < MiniTest::Test
   def test_puts_transport_content
     transport_details = {
       'ParcelData' => {
-        'PackageList' => {
+        'PackageList' => [
+          {
           'TrackingId' => '123'
-        }
+          }
+        ]
       }
     }
 
@@ -64,7 +66,7 @@ class TestMWSFulfillmentInboundShipmentClient < MiniTest::Test
       'ShipmentId' => '1',
       'IsPartnered' => true,
       'ShipmentType' => 'Foo',
-      'TransportDetails.ParcelData.PackageList.TrackingId' => '123'
+      'TransportDetails.ParcelData.PackageList.member.1.TrackingId' => '123'
     }
 
     @client.stub(:run, nil) do

data/test/unit/peddler/test_client.rb

@@ -4,7 +4,7 @@ require 'peddler/client'
 
 class TestPeddlerClient < MiniTest::Test
   module Parser
-    def self.parse(res, *); res; end
+    def self.new(res, *); res; end
   end
 
   def setup
@@ -134,7 +134,24 @@ class TestPeddlerClient < MiniTest::Test
     assert headers.has_key?('User-Agent')
   end
 
-  def test_error_callback
+  def test_error_callback_on_class
+    Excon.stub({}, { status: 503 })
+
+    assert_raises(Excon::Errors::ServiceUnavailable) do
+      @client.run
+    end
+
+    @klass.on_error do |_, res|
+      assert_equal 503, res.status
+    end
+
+    @client.run
+
+    Excon.stubs.clear
+    @klass.instance_variable_set(:@error_handler, nil)
+  end
+
+  def test_error_callback_on_instance
     Excon.stub({}, { status: 503 })
 
     assert_raises(Excon::Errors::ServiceUnavailable) do
@@ -149,4 +166,40 @@ class TestPeddlerClient < MiniTest::Test
 
     Excon.stubs.clear
   end
+
+  def test_error_callback_on_client_ancestor
+    Excon.stub({}, { status: 503 })
+
+    assert_raises(Excon::Errors::ServiceUnavailable) do
+      @client.run
+    end
+
+    Peddler::Client.on_error do |_, res|
+      assert_equal 503, res.status
+    end
+
+    klass = Class.new(Peddler::Client)
+    klass.parser = Parser
+    client = klass.new
+    client.aws_access_key_id = 'key'
+    client.aws_secret_access_key = 'secret'
+    client.merchant_id = 'seller'
+    client.marketplace_id = 'ATVPDKIKX0DER' # US
+    client.operation('Foo')
+    client.run
+
+    Excon.stubs.clear
+    Peddler::Client.instance_variable_set(:@error_handler, nil)
+  end
+
+  def test_deprecates_call_to_parser_parse
+    deprecated_parser = Module.new do
+      def self.parse(res, *); res; end
+    end
+    @client.stub :warn, nil do
+      @klass.parser = deprecated_parser
+      res = @client.run
+      assert_equal @body, res.body
+    end
+  end
 end

data/test/unit/peddler/test_marketplace.rb

@@ -14,8 +14,14 @@ class TestPeddlerMarketplace < MiniTest::Test
     assert @marketplace.encoding
   end
 
-  def test_guards_against_bad_marketplace_ids
-    assert_raises(Peddler::Marketplace::BadId) do
+  def test_guard_against_missing_marketplace_id
+    assert_raises(Peddler::Marketplace::BadId, 'missing MarketplaceId') do
+      marketplace = Peddler::Marketplace.new(nil)
+    end
+  end
+
+  def test_guard_against_bad_marketplace_id
+    assert_raises(Peddler::Marketplace::BadId, '"123" is not a valid MarketplaceId') do
       marketplace = Peddler::Marketplace.new('123')
       marketplace.host
     end

data/test/unit/peddler/test_parser.rb

@@ -5,7 +5,7 @@ class TestPeddlerParser < MiniTest::Test
   def assert_parser(klass, *content_types)
     content_types.each do |content_type|
       res = OpenStruct.new(headers: { 'Content-Type' => content_type }, body: '')
-      parser = Peddler::Parser.parse(res)
+      parser = Peddler::Parser.new(res)
 
       assert_kind_of klass, parser
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: peddler
 version: !ruby/object:Gem::Version
-  version: 0.12.7
+  version: 0.13.0
 platform: ruby
 authors:
 - Hakan Ensari
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-05 00:00:00.000000000 Z
+date: 2015-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jeff
@@ -79,15 +79,12 @@ files:
 - lib/peddler.rb
 - lib/peddler/client.rb
 - lib/peddler/flat_file_parser.rb
-- lib/peddler/flat_file_response.rb
 - lib/peddler/marketplace.rb
 - lib/peddler/operation.rb
 - lib/peddler/parser.rb
-- lib/peddler/response.rb
 - lib/peddler/structured_list.rb
 - lib/peddler/version.rb
 - lib/peddler/xml_parser.rb
-- lib/peddler/xml_response.rb
 - test/helper.rb
 - test/integration/test_cart_information.rb
 - test/integration/test_customer_information.rb

data/lib/peddler/flat_file_response.rb

@@ -1,53 +0,0 @@
-require 'delegate'
-require 'csv'
-require 'digest/md5'
-
-module Peddler
-  # @api private
-  class FlatFileResponse < SimpleDelegator
-    # http://stackoverflow.com/questions/8073920/importing-csv-quoting-error-is-driving-me-nuts
-    OPTIONS = { col_sep: "\t", quote_char: "\x00", headers: true }
-
-    attr_reader :content, :summary, :encoding
-
-    def initialize(res, encoding)
-      super(res)
-      @encoding = encoding
-      extract_content
-    end
-
-    def parse
-      CSV.parse(scrub_content, OPTIONS) if content
-    end
-
-    def records_count
-      summarize if summary?
-    end
-
-    def valid?
-      headers['Content-MD5'] == Digest::MD5.base64digest(body)
-    end
-
-    private
-
-    def extract_content
-      if summary?
-        @summary, @content = body.split("\n\n")
-      else
-        @content = body.dup
-      end
-    end
-
-    def scrub_content
-      content.force_encoding(encoding).encode('UTF-8')
-    end
-
-    def summary?
-      body.start_with?('Feed Processing Summary')
-    end
-
-    def summarize
-      Hash[summary.split("\n\t")[1, 2].map { |line| line.split("\t\t") }]
-    end
-  end
-end

data/lib/peddler/response.rb

@@ -1,24 +0,0 @@
-require 'peddler/flat_file_response'
-require 'peddler/xml_response'
-
-module Peddler
-  # @api private
-  module Response
-    # The inevitable messiness of massaging data produced by a motley army of
-    # Amazon developers
-    def self.new(response, encoding = 'ISO-8859-1')
-      # Don't parse if there's no body
-      return response unless response.body
-
-      content_type = response.headers['Content-Type']
-      if content_type.start_with?('text/xml')
-        XMLResponse.new(response)
-      else
-        # Amazon returns a variety of content types for flat files, so we
-        # simply assume that anything not XML is a flat file rather than code
-        # defensively and check content type again.
-        FlatFileResponse.new(response, encoding)
-      end
-    end
-  end
-end

data/lib/peddler/xml_response.rb

@@ -1,30 +0,0 @@
-require 'delegate'
-require 'multi_xml'
-
-module Peddler
-  # @api private
-  class XMLResponse < SimpleDelegator
-    def next_token
-      parse.fetch('NextToken', false)
-    end
-
-    def parse
-      @result ||= find_result
-    end
-
-    def document
-      MultiXml.parse(body)
-    end
-
-    def valid?
-      headers['Content-Length'].to_i == body.size if headers['Content-Length']
-    end
-
-    private
-
-    def find_result
-      results = document.values[0].find { |k, _| k.include?('Result') }
-      results ? results.last : nil
-    end
-  end
-end