vacuum 2.2.0 → 3.4.0

data/lib/vacuum/operation.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'aws-sigv4'
+require 'http'
+require 'json'
+
+module Vacuum
+  # An Amazon Product Advertising API operation
+  class Operation
+    # @!visibility private
+    attr_reader :locale, :name, :params
+
+    # Creates a new operation
+    #
+    # @param [String] name
+    # @param [Hash] params
+    # @param [Locale] locale
+    def initialize(name, params:, locale:)
+      @name = name
+      @params = params
+      @locale = locale
+    end
+
+    # @return [Hash]
+    def headers
+      signature.headers.merge(
+        'x-amz-target' =>
+          "com.amazon.paapi5.v1.ProductAdvertisingAPIv1.#{name}",
+        'content-encoding' => 'amz-1.0',
+        'content-type' => 'application/json; charset=utf-8'
+      )
+    end
+
+    # @return [String]
+    def body
+      @body ||= build_body
+    end
+
+    # @return [String]
+    def url
+      @url ||= build_url
+    end
+
+    private
+
+    def build_body
+      hsh = { 'PartnerTag' => locale.partner_tag,
+              'PartnerType' => locale.partner_type }
+
+      params.each do |key, val|
+        key = key.to_s.split('_')
+                 .map { |word| word == 'asin' ? 'ASIN' : word.capitalize }.join
+        hsh[key] = val
+      end
+
+      JSON.generate(hsh)
+    end
+
+    def build_url
+      "https://#{locale.host}/paapi5/#{name.downcase}"
+    end
+
+    def signature
+      signer.sign_request(http_method: 'POST', url: url, body: body)
+    end
+
+    def signer
+      Aws::Sigv4::Signer.new(service: 'ProductAdvertisingAPI',
+                             region: locale.region,
+                             access_key_id: locale.access_key,
+                             secret_access_key: locale.secret_key,
+                             http_method: 'POST', endpoint: locale.host)
+    end
+  end
+end

data/lib/vacuum/request.rb

@@ -1,122 +1,189 @@
 # frozen_string_literal: true
 
-require 'jeff'
+require 'http'
+
+require 'vacuum/locale'
+require 'vacuum/operation'
+require 'vacuum/resource'
 require 'vacuum/response'
 
 module Vacuum
-  # An Amazon Product Advertising API request.
+  # A request to the Amazon Product Advertising API
   class Request
-    include Jeff
-
-    BadLocale = Class.new(ArgumentError)
-
-    LATEST_VERSION = '2013-08-01'
-
-    HOSTS = {
-      'AU' => 'webservices.amazon.com.au',
-      'BR' => 'webservices.amazon.com.br',
-      'CA' => 'webservices.amazon.ca',
-      'CN' => 'webservices.amazon.cn',
-      'DE' => 'webservices.amazon.de',
-      'ES' => 'webservices.amazon.es',
-      'FR' => 'webservices.amazon.fr',
-      'GB' => 'webservices.amazon.co.uk',
-      'IN' => 'webservices.amazon.in',
-      'IT' => 'webservices.amazon.it',
-      'JP' => 'webservices.amazon.co.jp',
-      'MX' => 'webservices.amazon.com.mx',
-      'TR' => 'webservices.amazon.com.tr',
-      'US' => 'webservices.amazon.com'
-    }.freeze
-
-    OPERATIONS = %w[
-      BrowseNodeLookup
-      CartAdd
-      CartClear
-      CartCreate
-      CartGet
-      CartModify
-      ItemLookup
-      ItemSearch
-      SimilarityLookup
-    ].freeze
-    private_constant :OPERATIONS
-
-    params 'AssociateTag' => -> { associate_tag },
-           'Service' => 'AWSECommerceService',
-           'SubscriptionId' => -> { subscription_id },
-           'Version' => -> { version }
-
-    attr_accessor :associate_tag, :subscription_id
-    attr_writer :version
-
-    # Create a new request for given locale.
-    #
-    # locale - The String Product Advertising API locale (default: US).
-    # secure - Whether to use the secure version of the endpoint (default:
-    #          false)
+    # @return [HTTP::Client]
+    attr_reader :client
+
+    # @return [Locale]
+    attr_reader :locale
+
+    # @return [Operation]
+    attr_reader :operation
+
+    # Creates a new request
     #
-    # Raises a Bad Locale error if locale is not valid.
-    def initialize(locale = 'US', secure = false)
-      locale = 'GB' if locale == 'UK'
-      host = HOSTS.fetch(locale) { raise BadLocale }
-      @aws_endpoint = "#{secure ? 'https' : 'http'}://#{host}/onca/xml"
+    # @overload initialize(marketplace: :us, access_key:, secret_key:, partner_tag:, partner_type:)
+    #   @param [Symbol,String] marketplace
+    #   @param [String] access_key
+    #   @param [String] secret_key
+    #   @param [String] partner_tag
+    #   @param [String] partner_type
+    #   @raise [Locale::NotFound] if marketplace is not found
+    def initialize(marketplace: :us, **args)
+      @locale = Locale.new(marketplace, **args)
+      @client = HTTP::Client.new
     end
 
-    # Configure the Amazon Product Advertising API request.
-    #
-    # credentials - The Hash credentials of the API endpoint.
-    #               :aws_access_key_id     - The String Amazon Web Services
-    #                                        (AWS) key.
-    #               :aws_secret_access_key - The String AWS secret.
-    #               :associate_tag         - The String Associate Tag.
-    #               :aws_version           - The String AWS version.
+    # Returns details about specified browse nodes
     #
-    # Returns self.
-    def configure(credentials)
-      credentials.each { |key, val| send("#{key}=", val) }
-      self
+    # @see https://webservices.amazon.com/paapi5/documentation/getbrowsenodes.html
+    # @overload get_browse_nodes(browse_node_ids:, languages_of_preference: nil, marketplace: nil, partner_tag: nil, partner_type: nil, resources: nil)
+    #   @param [Array<String,Integer>,String,Integer] browse_node_ids
+    #   @param [Array<String>,nil] languages_of_preference
+    #   @param [String,nil] marketplace
+    #   @param [String,nil] partner_tag
+    #   @param [String,nil] partner_type
+    #   @param [Array<String>,nil] resources
+    # @return [Response]
+    def get_browse_nodes(browse_node_ids:, **params)
+      params.update(browse_node_ids: Array(browse_node_ids))
+      request('GetBrowseNodes', params)
     end
 
-    # Returns the API version.
-    def version
-      @version || LATEST_VERSION
+    # Returns the attributes of one or more items
+    #
+    # @see https://webservices.amazon.com/paapi5/documentation/get-items.html
+    # @overload get_items(condition: nil, currency_of_preference: nil, item_id_type: nil, item_ids:, languages_of_preference: nil, marketplace: nil, merchant: nil, offer_count: nil, partner_tag: nil, partner_type: nil, resources: nil)
+    #   @param [String,nil] condition
+    #   @param [String,nil] currency_of_preference
+    #   @param [String,nil] item_id_type
+    #   @param [Array<String>,String] item_ids
+    #   @param [Array<String>,nil] languages_of_preference
+    #   @param [String,nil] marketplace
+    #   @param [String,nil] merchant
+    #   @param [Integer,nil] offer_count
+    #   @param [String,nil] partner_tag
+    #   @param [String,nil] partner_type
+    #   @param [Array<String>,nil] resources
+    # @return [Response]
+    def get_items(item_ids:, **params)
+      params.update(item_ids: Array(item_ids))
+      request('GetItems', params)
     end
 
-    # Execute an API operation. See `OPERATIONS` constant above for available
-    # operation names.
+    # Returns a set of items that are the same product, but differ according to
+    # a consistent theme
     #
-    # params - The Hash request parameters.
-    # opts   - Options passed to Excon (default: {}).
+    # @see https://webservices.amazon.com/paapi5/documentation/get-variations.html
+    # @overload get_variations(asin:, condition: nil, currency_of_preference: nil, languages_of_preference: nil, marketplace: nil, merchant: nil, offer_count: nil, partner_tag: nil, partner_type: nil, resources: nil, variation_count: nil, variation_page: nil)
+    #   @param [String] asin
+    #   @param [String,nil] condition
+    #   @param [String,nil] currency_of_preference
+    #   @param [Array<String>,nil] languages_of_preference
+    #   @param [String,nil] marketplace
+    #   @param [String,nil] merchant
+    #   @param [Integer,nil] offer_count
+    #   @param [String,nil] partner_tag
+    #   @param [String,nil] partner_type
+    #   @param [Array<String>,nil] resources
+    #   @param [Integer,nil] variation_count
+    #   @param [Integer,nil] variation_page
+    #   @return [Response]
+    def get_variations(**params)
+      request('GetVariations', params)
+    end
+
+    # Searches for items on Amazon based on a search query
     #
-    # Alternatively, pass Excon options as first argument and include request
-    # parameters as query key.
+    # @see https://webservices.amazon.com/paapi5/documentation/search-items.html
+    # @overload search_items(actor: nil, artist: nil, author: nil, availability: nil, brand: nil, browse_node_id: nil, condition: nil, currency_of_preference: nil, delivery_flags: nil, item_count: nil, item_page: nil, keywords: nil, languages_of_preference: nil, marketplace: nil, max_price: nil, merchant: nil, min_price: nil, min_reviews_rating: nil, min_savings_percent: nil, offer_count: nil, partner_tag: nil, partner_type: nil, resources: nil, search_index: nil, sort_by: nil, title: nil)
+    #   @param [String,nil] actor
+    #   @param [String,nil] artist
+    #   @param [String,nil] availability
+    #   @param [String,nil] brand
+    #   @param [Integer,nil] browse_node_id
+    #   @param [String,nil] condition
+    #   @param [String,nil] currency_of_preference
+    #   @param [Array<String>,nil] delivery_flags
+    #   @param [Integer,nil] item_count
+    #   @param [Integer,nil] item_page
+    #   @param [String,nil] keywords
+    #   @param [Array<String>,nil] languages_of_preference
+    #   @param [Integer,nil] max_price
+    #   @param [String,nil] merchant
+    #   @param [Integer,nil] min_price
+    #   @param [Integer,nil] min_reviews_rating
+    #   @param [Integer,nil] min_savings_percent
+    #   @param [Integer,nil] offer_count
+    #   @param [Hash,nil] properties
+    #   @param [Array<String>,nil] resources
+    #   @param [String,nil] search_index
+    #   @param [String,nil] sort_by
+    #   @param [String,nil] title
+    # @return [Response]
+    def search_items(**params)
+      request('SearchItems', params)
+    end
+
+    # Flags as persistent
     #
-    # Examples
+    # @param [Integer] timeout
+    # @return [self]
+    def persistent(timeout: 5)
+      host = "https://#{locale.host}"
+      @client = client.persistent(host, timeout: timeout)
+
+      self
+    end
+
+    # @!method use(*features)
+    #   Turn on {https://github.com/httprb/http HTTP} features
     #
-    #   req.item_search(
-    #     'SearchIndex' => 'All',
-    #     'Keywords' => 'Architecture'
-    #   )
+    #   @param features
+    #   @return [self]
     #
-    #   req.item_search(
-    #     query: {
-    #       'SearchIndex' => 'All',
-    #       'Keywords' => 'Architecture'
-    #     },
-    #     persistent: true
-    #   )
+    # @!method via(*proxy)
+    #   Make a request through an HTTP proxy
     #
-    # Returns a Vacuum Response.
-    OPERATIONS.each do |operation|
-      method_name = operation.gsub(/(.)([A-Z])/, '\1_\2').downcase
-      define_method(method_name) do |params, opts = {}|
-        params.key?(:query) ? opts = params : opts.update(query: params)
-        opts[:expects] ||= [200, 400, 403]
-        opts[:query].update('Operation' => operation)
-
-        Response.new(get(opts))
+    #   @param [Array] proxy
+    #   @raise [HTTP::Request::Error] if HTTP proxy is invalid
+    #   @return [self]
+    %i[timeout via through headers use].each do |method_name|
+      define_method(method_name) do |*args, &block|
+        @client = client.send(method_name, *args, &block)
       end
     end
+
+    private
+
+    def validate(params)
+      validate_keywords(params)
+      validate_resources(params)
+    end
+
+    def validate_keywords(params)
+      return unless params[:keywords]
+      return if params[:keywords].is_a?(String)
+
+      raise ArgumentError, ':keyword argument expects a String'
+    end
+
+    def validate_resources(params)
+      return unless params[:resources]
+
+      raise ArgumentError, ':resources argument expects an Array' unless params[:resources].is_a?(Array)
+
+      params[:resources].each do |resource|
+        raise ArgumentError, "There is not such resource: #{resource}" unless Resource.valid?(resource)
+      end
+    end
+
+    def request(operation_name, params)
+      validate(params)
+      @operation = Operation.new(operation_name, params: params, locale: locale)
+      response = client.headers(operation.headers)
+                       .post(operation.url, body: operation.body)
+
+      Response.new(response)
+    end
   end
 end

data/lib/vacuum/resource.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Vacuum
+  # Resources determine what information will be returned in the API response
+  #
+  # @see https://webservices.amazon.com/paapi5/documentation/resources.html
+  class Resource
+    ALL = %w[BrowseNodeInfo.BrowseNodes
+             BrowseNodeInfo.BrowseNodes.Ancestor
+             BrowseNodeInfo.BrowseNodes.SalesRank
+             BrowseNodeInfo.WebsiteSalesRank
+             Images.Primary.Small
+             Images.Primary.Medium
+             Images.Primary.Large
+             Images.Variants.Small
+             Images.Variants.Medium
+             Images.Variants.Large
+             ItemInfo.ByLineInfo
+             ItemInfo.Classifications
+             ItemInfo.ContentInfo
+             ItemInfo.ContentRating
+             ItemInfo.ExternalIds
+             ItemInfo.Features
+             ItemInfo.ManufactureInfo
+             ItemInfo.ProductInfo
+             ItemInfo.TechnicalInfo
+             ItemInfo.Title
+             ItemInfo.TradeInInfo
+             Offers.Listings.Availability.MaxOrderQuantity
+             Offers.Listings.Availability.Message
+             Offers.Listings.Availability.MinOrderQuantity
+             Offers.Listings.Availability.Type
+             Offers.Listings.Condition
+             Offers.Listings.Condition.SubCondition
+             Offers.Listings.DeliveryInfo.IsAmazonFulfilled
+             Offers.Listings.DeliveryInfo.IsFreeShippingEligible
+             Offers.Listings.DeliveryInfo.IsPrimeEligible
+             Offers.Listings.IsBuyBoxWinner
+             Offers.Listings.LoyaltyPoints.Points
+             Offers.Listings.MerchantInfo
+             Offers.Listings.Price
+             Offers.Listings.ProgramEligibility.IsPrimeExclusive
+             Offers.Listings.ProgramEligibility.IsPrimePantry
+             Offers.Listings.Promotions
+             Offers.Listings.SavingBasis
+             Offers.Summaries.HighestPrice
+             Offers.Summaries.LowestPrice
+             Offers.Summaries.OfferCount
+             ParentASIN].freeze
+    private_constant :ALL
+
+    # @!attribute [r] all
+    # @return [Array<String>]
+    def self.all
+      ALL
+    end
+
+    def self.valid?(resource)
+      ALL.include?(resource)
+    end
+  end
+end

data/lib/vacuum/response.rb

@@ -2,35 +2,47 @@
 
 require 'delegate'
 require 'forwardable'
-require 'multi_xml'
+require 'json'
 
 module Vacuum
-  # A wrapper around the Amazon Product Advertising API response.
+  # A wrapper around the API response
   class Response < SimpleDelegator
     extend Forwardable
 
+    # @!method dig(*key)
+    #   Delegates to the Hash returned by {Response#to_h} to extract a nested
+    #   value specified by the sequence of keys
+    #
+    #   @param [String] key one or more keys
+    #   @see https://ruby-doc.org/core/Hash.html#method-i-dig
+    def_delegator :to_h, :dig
+
     class << self
+      # @return [nil,.parse] an optional custom parser
       attr_accessor :parser
     end
 
-    def_delegator :to_h, :dig
-
+    # @return [nil,.parse] an optional custom parser
     attr_writer :parser
 
+    # @!attribute [r] parser
+    # @return [nil,.parse] an optional custom parser
     def parser
       @parser || self.class.parser
     end
 
+    # Parses the response body
+    #
+    # @note Delegates to {#to_h} if no custom parser is set
     def parse
       parser ? parser.parse(body) : to_h
     end
 
+    # Casts body to Hash
+    #
+    # @return [Hash]
     def to_h
-      MultiXml.parse(body)
-    end
-
-    def body
-      (+__getobj__.body).force_encoding(Encoding::UTF_8)
+      JSON.parse(body)
     end
   end
 end