ramazon_advertising 0.3.2

data/features/step_definitions/product_steps.rb

@@ -0,0 +1,75 @@
+When /^I try to find the asin "([^\"]*)"$/ do |asin|
+  @products = Ramazon::Product.find(:item_id => asin, :response_group => ["Medium", "BrowseNodes", "Offers"])
+  @product = @products[0]
+end
+
+Given /^I am searching with the "([^\"]*)" of "([^\"]*)"$/ do |attr, value|
+  @search_options ||= {}
+  @search_options[attr.to_sym] = value
+end
+
+When /^I perform the product search$/ do
+  begin
+    @search_options ||= {}
+    @products = Ramazon::Product.find(@search_options)
+  rescue Ramazon::Error => e
+    @error = e
+  end
+end
+
+Then /^I should get a list of products$/ do
+  raise @error if @error
+  @products.should_not be_empty
+end
+
+Then /^the list of products should have more than (\d+) product$/ do |count|
+  @products.should have_at_least(count.to_i + 1).items
+end
+
+
+Then /^each product should have the "([^\"]*)" "([^\"]*)"$/ do |attr, value|
+  @products.each do |p|
+    p.send(attr).should eql(value)
+  end
+end
+
+Then /^I should get a product$/ do
+  raise @error if @error
+  @product = @products[0] unless @product
+  @product.should_not be_nil
+end
+
+Then /^the product should have (the\s)?"([^\"]*)" "([^\"]*)"$/ do |the, attr, value|
+  @product.send(attr).should eql(value)
+end
+
+Then /^the product should have (a\s)?"([^\"]*)"$/ do |a, attr|
+  @product.send(attr).should_not be_nil
+end
+
+Then /^each of the product's "([^\"]*)" should have a "([^\"]*)"$/ do |collection_name, attr|
+  @product.send(collection_name).should_not be_empty
+  @product.send(collection_name).each do |i|
+    i.send(attr).should_not be_nil
+  end
+end
+
+Then /^each of the product's "([^\"]*)" should have a "([^\"]*)" of "([^\"]*)"$/ do |collection_name, attr, value|
+  @product.send(collection_name).should_not be_empty
+  @product.send(collection_name).each do |i|
+    i.send(attr).should_not be_nil
+  end
+end
+
+
+Then /^the product should have a category tree for "([^\"]*)"$/ do |category_name|
+  @product.category_tree[category_name].should_not be_nil
+end
+
+
+Then /^each product should have (a\s)?"([^\"]*)"$/ do |a, attr|
+  @products.each do |p|
+    p.send(attr).should_not be_nil
+  end
+end
+

data/features/support/env.rb

@@ -0,0 +1,7 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__) + '..', '..', 'lib'))
+require 'lib/ramazon_advertising'
+
+require 'spec/expectations'
+
+configatron.ramazon.configure_from_yaml(File.join(File.dirname(__FILE__), "ramazon_advertising.yml"))
+

data/features/support/ramazon_advertising.example.yml

@@ -0,0 +1,2 @@
+access_key: SOMETHING
+secret_key: SOMETHING SECRET

data/lib/ramazon/abstract_element.rb

@@ -0,0 +1,18 @@
+module Ramazon
+  module AbstractElement
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def abstract_element(name, type, options = {})
+        element(name, type, options.merge(:parser => :abstract_parse, :raw => true))
+      end
+
+      def abstract_parse(xml, options = {})
+        tag XML::Parser.string(xml).parse.root.name
+        parse(xml)
+      end
+    end
+  end
+end

data/lib/ramazon/browse_node.rb

@@ -0,0 +1,69 @@
+module Ramazon
+  class BrowseNode
+    include HTTParty
+    include HappyMapper
+
+    tag "BrowseNode"
+
+    element :name, String, :tag => "Name"
+    element :node_id, String, :tag => "BrowseNodeId"
+    element :children, Ramazon::BrowseNode, :tag => "Children/BrowseNode"
+    element :is_category_root, Boolean, :tag => "IsCategoryRoot"
+
+    attr_accessor :child
+    
+    DEFAULT_ROOT_FILE = File.join(File.dirname(__FILE__), '..', 'root_nodes.yml')
+
+    def self.generate_root_nodes(file_name = DEFAULT_ROOT_FILE)
+      if Ramazon::Configuration.locale == :us
+        doc = Nokogiri::HTML(get('http://www.amazon.com').body)
+        root_nodes = {}
+        doc.search(".navSaMenu .navSaChildItem a").each do |element|
+          if element["href"] =~ /node=(\d+)\&/
+            root_nodes[element.content] = $1
+          end
+        end
+
+        unless root_nodes.empty?
+          FileUtils.rm_f(file_name)
+          File.open(file_name, 'w') do |f|
+            f.write(root_nodes.to_yaml)
+          end
+        end
+      else
+        #todo correlate ECS locales to actual amazon.* urls
+        raise "generating root nodes for locale's other than the US is not supported"
+      end
+    end
+
+    def self.root_nodes(file_name = DEFAULT_ROOT_FILE)
+      @root_nodes ||= File.open(file_name) { |yf| YAML::load(yf) }
+    end
+
+    # find a browse node based on its id
+    # @param node_id [String] the browse node you're looking for
+    # @returns [Ramazon::BrowseNode] the node you're looking for
+    def self.find(node_id)
+      req = Ramazon::Request.new(:operation => "BrowseNodeLookup", :browse_node_id => node_id)
+      res = req.submit
+      parse(res.to_s)[0]
+    end
+
+    # get a hash of name -> child browse_nodes
+    # @returns [Hash] stringified hash of names => Ramazon::BrowseNode objects
+    def child_hash
+      if !@child_hash
+        @child_hash = {}
+        self.children.each do |i|
+          @child_hash[i.name] = i
+        end
+      end
+
+      @child_hash
+    end
+
+    def self.parse(xml, options = {})
+      super
+    end
+  end
+end

data/lib/ramazon/configuration.rb

@@ -0,0 +1,66 @@
+module Ramazon
+  # the class that persists configuration information for Amazon requests
+  class Configuration
+    class << self
+      LOCALES = [:ca, :de, :fr, :jp, :uk, :us]
+
+      # set the locale for future requests
+      # will raise an exception if the locale isn't in the Configuration::LOCALES collection
+      def locale=(locale)
+        if LOCALES.include?(locale)
+          configatron.ramazon.locale = locale
+        else
+          raise "unknown locale"
+        end
+      end
+
+      # get the current locale (defaults to the us)
+      def locale
+        configatron.ramazon.locale || :us
+      end
+
+      # get the current access key
+      def access_key
+        configatron.ramazon.access_key
+      end
+
+      # set the current access key
+      # @param key [String] access key you're using to access the advertising api
+      def access_key=(key)
+        configatron.ramazon.access_key = key
+      end
+
+      # get the current secret key that is used for request signing
+      def secret_key
+        configatron.ramazon.secret_key
+      end
+
+      # set the secret key so that requests can be appropriately signed
+      # @param key [String] secret key you're using to sign advertising requests
+      def secret_key=(key)
+        configatron.ramazon.secret_key = key
+      end
+
+      # get the correct host based on your locale
+      def base_uri
+        if locale == :us
+          "http://ecs.amazonaws.com"
+        else
+          "http://ecs.amazonaws.#{locale}"
+        end
+      end
+
+      # get the full path including locale specific host and /onca/xml path
+      def uri
+        "#{base_uri}#{path}"
+      end
+
+      # get the path where requests should be dispatched to
+      def path
+        "/onca/xml"
+      end
+
+      
+    end
+  end
+end

data/lib/ramazon/error.rb

@@ -0,0 +1,12 @@
+module Ramazon
+  class Error < StandardError
+    include HappyMapper
+    tag "Error"
+    element :code, String, :tag => "Code"
+    element :message, String, :tag => "Message"
+
+    def to_s
+      "#{self.code}: #{self.message}"
+    end
+  end
+end

data/lib/ramazon/image.rb

@@ -0,0 +1,18 @@
+module Ramazon
+  # An image object returned by Amazon's product data
+  # Available accessors include
+  # +url+::
+  #   The url of the image
+  # +height+::
+  #   The height of the image
+  # +width+::
+  #   The width of the image 
+  class Image
+    include HappyMapper
+    include Ramazon::AbstractElement
+    tag "Image"
+    element :url, String, :tag => "URL"
+    element :height, Integer, :tag => "Height"
+    element :width, Integer, :tag => "Width" 
+  end
+end

data/lib/ramazon/merchant.rb

@@ -0,0 +1,21 @@
+module Ramazon
+  # Merchant Details
+  # Current supports the following accessors
+  # +merchant_id+::
+  #   The id of the merchant
+  # +glance_page_url+::
+  #   The url of the merchant
+  # +average_feedback_rating+::
+  #   Average Feedback Rating
+  # +total_feedback+::
+  #   Total Feedback
+  class Merchant
+    include HappyMapper
+    tag "Merchant"
+
+    element :merchant_id, String, :tag => "MerchantId"
+    element :glance_page_url, String, :tag => "GlancePage"
+    element :average_feedback_rating, Float, :tag => "AverageFeedbackRating"
+    element :total_feedback, Integer, :tag => "TotalFeedback"
+  end
+end

data/lib/ramazon/offer.rb

@@ -0,0 +1,27 @@
+module Ramazon
+  # Offer Details
+  # Currently supports the following accessors 
+  # +merchant+::
+  #   The merchant that is listing this product (NOTE: Returns Ramazon::Merchant object)
+  # +condition+::
+  #   The condition of the product
+  # +sub_condition+::
+  #   The subcondition of the product
+  # +listing_id+::
+  #   The id of the listing
+  # +price+::
+  #   The asking price of the listing (NOTE: Returns Ramazon::Price object)
+  class Offer
+    include HappyMapper
+    include Ramazon::AbstractElement
+
+    tag "Offer"
+
+    has_one :merchant, Ramazon::Merchant, :tag => "Merchant"
+    element :condition, String, :tag => "OfferAttributes/Condition"
+    element :sub_condition, String, :tag => "OfferAttributes/SubCondition"
+    element :listing_id, String, :tag => "OfferListing/OfferListingId"
+    abstract_element :price, Ramazon::Price, :tag => "OfferListing/Price"
+
+  end
+end

data/lib/ramazon/price.rb

@@ -0,0 +1,18 @@
+module Ramazon
+  # A price object returned by Amazon's product data
+  # Available accessors include
+  # +amount+::
+  #   The unformatted ammount of the price
+  # +currency_code+::
+  #   The currency of the offer
+  # +formatted_price+::
+  #   The formatted price of the offer
+  class Price
+    include HappyMapper
+    include Ramazon::AbstractElement
+
+    element :amount, String, :tag => "Amount"
+    element :currency_code, String, :tag => "CurrencyCode"
+    element :formatted_price, String, :tag => "FormattedPrice"
+  end
+end

data/lib/ramazon/product.rb

@@ -0,0 +1,303 @@
+module Ramazon
+  # Find and get product details with this class
+  # Currently supports the following accessors 
+  # (all other elements can be accessed via nokogiri selectors and the get method)
+  # +asin+::
+  #   Amazon Identifier
+  # +upc+::
+  #   UPC ID
+  # +title+::
+  #   Title of the product
+  # +product_group+::
+  #   The category/product_group of the product
+  # +manufacturer+::
+  #   The manufacturer of the product
+  # +brand+::
+  #   The brand of the product
+  # +url+::
+  #   The Amazon URL of the product
+  # +small_image+::
+  #   The small image that Amazon provides (NOTE: Returns Ramazon::Image object)
+  # +medium_image+::
+  #   The medium image that Amazon provides (NOTE: Returns Ramazon::Image object)
+  # +large_image+::
+  #   The large image that Amazon provides (NOTE: Returns Ramazon::Image object)
+  # +list_price+::
+  #   The list price of the item (NOTE: Returns Ramazon::Price object)
+  # +lowest_new_price+::
+  #   The lowest new price from the offer summary (NOTE: Returns Ramazon::Price object)
+  # +sales_rank+::
+  #   The sales rank of the product
+  # +new_count+::
+  #   The quantity of new item offers
+  # +used_count+::
+  #   The quantity of used item offers
+  # +collectible_count+::
+  #   The quantity of collectible item offers
+  # +refurbished_count+::
+  #   The quantity of refurbished item offers
+  # +release_date+::
+  #   The release date of the product
+  # +original_release_date+::
+  #   The original release date of the product
+  # +offers+::
+  #   The collection of offers available for the given product
+  # @example find an individual item
+  #   @products = Ramazon::Product.find(:item_id => "B000NU2CY4", :response_group => "Medium")
+  #   @products[0].title
+  #   @products[0].asin
+  #   @products[0].upc
+  #   @products[0].large_image.url
+  #   @products[0].url
+  #
+
+  class Product
+    include HappyMapper
+    include Ramazon::AbstractElement
+    tag 'Item'
+
+    element :asin, String, :tag => 'ASIN'
+    element :upc, String, :tag => 'ItemAttributes/UPC'
+    element :title, String, :tag => 'Title', :deep => true
+    element :product_group, String, :tag => 'ItemAttributes/ProductGroup'
+    element :manufacturer, String, :tag => 'ItemAttributes/Manufacturer'
+    element :brand, String, :tag => 'ItemAttributes/Brand'
+    element :url, String, :tag => 'DetailPageURL'
+    abstract_element :small_image, Ramazon::Image, :tag => "SmallImage"
+    abstract_element :large_image, Ramazon::Image, :tag => "LargeImage"
+    abstract_element :medium_image, Ramazon::Image, :tag => "MediumImage"
+    abstract_element :tiny_image, Ramazon::Image, :tag => "TinyImage"
+    abstract_element :thumb_image, Ramazon::Image, :tag => "ThumbImage"
+    abstract_element :list_price, Ramazon::Price, :tag => "ItemAttributes/ListPrice"
+    abstract_element :lowest_new_price, Ramazon::Price, :tag => "OfferSummary/LowestNewPrice"
+    has_many :offers, Ramazon::Offer, :tag => "Offers/Offer"
+
+    element :sales_rank, Integer, :tag => "SalesRank"
+
+    element :new_count, Integer, :tag => "OfferSummary/TotalNew"
+    element :used_count, Integer, :tag => "OfferSummary/TotalUsed"
+    element :collectible_count, Integer, :tag => "OfferSummary/TotalCollectible"
+    element :refurbished_count, Integer, :tag => "OfferSummary/TotalRefurbished"
+
+    element :release_date, Date, :tag => 'ItemAttributes/ReleaseDate'
+    element :original_release_date, Date, :tag => 'ItemAttributes/OriginalReleaseDate'
+
+    attr_accessor :has_first_page_of_full_offers
+
+    # Creates the worker that performs the delta indexing
+    # @param options Amazon request options (you can use an underscore convention) 
+    # (ie. passing the :response_group option will be converted to "ResponseGroup")
+    # <tt>:item_id</tt> - the ASIN or UPC you're looking for
+    # @return [Array] array of Ramazon::Product objects
+    def self.find(*args)
+      options = args.extract_options!
+      if options[:item_id]
+        item_lookup(options[:item_id], options)
+      else
+        options[:operation] ||= "ItemSearch"
+        options[:search_index] ||= "Blended"
+        options[:item_page] ||= 1
+        res = Ramazon::Request.new(options).submit
+        products = Ramazon::ProductCollection.create_from_results(options[:item_page] || 1, 10, res)
+        if find_options_retrieve_all_offers?(options)
+          products.each do |p|
+            p.has_first_page_of_full_offers = true
+            p.offer_pages = offer_pages_for(p)
+          end
+        end
+        products
+      end
+    end
+ 
+    # Performs an item lookup
+    # @param item_id the ASIN or UPC you're looking for
+    # @options additional Amazon request options (i.e. :response_group)
+    def self.item_lookup(item_id, options = {})
+      req = Ramazon::Request.new({:item_id => item_id, 
+        :operation => "ItemLookup"}.merge(options))
+      res = req.submit
+
+      Ramazon::ProductCollection.create_from_results(1,1,res)
+    end
+
+    # assembles the available images for the object
+    # @return [Hash] hash of symbolized image_name => Ramazon::Image pairs
+    def images
+      if !@images
+        @images = {}
+        @images[:thumb] = self.thumb_image if self.thumb_image
+        @images[:tiny_image] = self.tiny_image if self.tiny_image
+        @images[:small] = self.small_image if self.small_image   
+        @images[:medium] = self.medium_image if self.medium_image
+        @images[:large] = self.large_image if self.large_image
+      end
+    end
+
+    attr_accessor :xml_doc
+    def self.parse(xml, options = {})
+      node = XML::Parser.string(xml.to_s).parse.root
+      node.find("//Item").collect do |n|
+        p = super(n.to_s)
+        p.xml_doc = Nokogiri::XML.parse(n.to_s)
+        p
+      end
+    end
+
+    # perform a nokogiri search on the product's XML
+    # @param args Passes directly to a Nokogiri::Xml.parse(xml).search method
+    # @example find the actor
+    #   @product = Ramazon::Product.find(:item_id => "B000NU2CY4", :response_group => "Medium")[0]
+    #   @product.get("ItemAttributes Actor").collect{|a| a.content}
+    def get(*args)
+      result = @xml_doc.search(args)
+    end
+
+    # returns a hash of category browse nodes from the top down
+    def category_tree
+      @category_tree = {}
+      get_category_browse_nodes.each do |n|
+        build_category_tree(n)
+      end
+      @category_tree
+    end
+
+    # a sorted list of used offers
+    def used_offers
+      if @used_offers.nil?
+        @used_offers = []
+        self.offers.each do |o|
+          if o.condition.downcase == "used"
+            @used_offers << o
+          end
+        end
+        @used_offers.sort!{|a,b| a.price.amount <=> b.price.amount}
+      end
+      @used_offers
+    end
+
+    # breaks down all the offers in a nested hash of [condition][subcondition]
+    # note: this will load ALL offers into memory
+    # @return [Hash] a nest hash of offers [condition][subcondition] => Array of Ramazon::Offer objects
+    def offers_by_condition
+      @offer_hash = {}
+      offer_page = 1
+      
+      offers = offer_page(offer_page)
+      while offer_page <= offer_pages
+        offers.each do |o|
+          @offer_hash[o.condition.downcase] ||= {}
+          @offer_hash[o.condition.downcase][o.sub_condition] ||= []
+          @offer_hash[o.condition.downcase][o.sub_condition] << o
+        end
+
+        offer_page += 1
+        offers = offer_page(offer_page)
+      end
+
+      @offer_hash
+    end
+
+    # gets the number of offer pages for the specified product
+    # @param [Ramazon::Product] product the we want to get offer pages for
+    # @returns [Integer] number of offer pages
+    def self.offer_pages_for(product)
+      if !@offer_pages 
+        offer_page_tags = product.get("//Offers/TotalOfferPages")
+        if offer_page_tags.size > 0
+          offer_pages = offer_page_tags[0].content.to_i
+        else
+          offer_pages = 1
+        end
+      end
+
+      offer_pages
+    end
+
+    # get the lowest offers broken down by subcondition
+    # @return [Hash] a nested hash of prices ie ["new"]["mint"] => Ramazon::Offer
+    def lowest_offers
+      if @lowest_offers.nil?
+        @lowest_offers = {}
+        offers_by_condition.each do |condition, sub_conditions|
+          @lowest_offers[condition] = {}
+          sub_conditions.each do |sub_condition, col|
+            sorted_offers = col.sort{|a,b| a.price.amount.to_i <=> b.price.amount.to_i}
+            @lowest_offers[condition][sub_condition] = sorted_offers.first
+          end
+        end
+      end
+
+      @lowest_offers
+    end
+
+    def offer_pages=(pages)
+      @offer_pages = pages.to_i
+    end
+
+    def offer_pages
+      @offer_pages
+    end
+
+    #get offers from a given page
+    # @param page [Integer] the page number you want to get
+    # @return [Array] Array of Offers returned from the page
+    def offer_page(page = 1)
+      #get all offers
+      if page == 1 && has_first_page_of_full_offers
+        self.offers 
+      else
+        products = self.class.find(:item_id => self.asin, 
+          :response_group => "OfferListings",
+          :merchant_id => "All",
+          :condition => "All",
+          :offer_page => page)
+
+        if products
+          product = products[0] 
+          self.offer_pages = self.class.offer_pages_for(product)
+          product.offers
+        else
+          []
+        end
+      end
+    end
+
+    private
+    # recursive function used to generate a topdown category tree
+    def build_category_tree(n, child = nil)
+      amz_node = BrowseNode.parse(n.to_s)
+      amz_node.child = child unless child.nil?
+
+      if n.search("./IsCategoryRoot").size > 0
+        @category_tree[amz_node.name] ||= []
+        @category_tree[amz_node.name] << amz_node
+      else
+        parents = n.search("./Ancestors/BrowseNode")
+        if parents.size > 0
+          build_category_tree(parents[0], amz_node)
+        end
+      end
+
+
+    end
+
+    def get_category_browse_nodes
+      self.get("BrowseNodes BrowseNode IsCategoryRoot").collect do |n|
+        n.ancestors("//BrowseNodes/BrowseNode")
+      end
+    end
+
+    def self.find_options_retrieve_all_offers?(options = {})
+      if options[:response_group].is_a?(Array)
+        groups = options[:response_group].join(" ")
+      else
+        groups = options[:response_group] || ""
+      end
+
+      groups =~ /OfferListings/ && 
+        (options[:offer_page].nil? || options[:offer_page].to_i == 1) &&
+        (options[:merchant_id] == "All") &&
+        (options[:condition] == "All")
+    end
+  end
+end