walmart_open 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MGFiOWIwMDA1YjYxYjY3Yjc4OWM2OTlhZmU3ZjlkNDA2MDIwZmQ0Mw==
+  data.tar.gz: !binary |-
+    NTMzNWFhODAxZDRkNWRmNTE4MzNkYTVlYTI4NjdmNjc1YTAxY2U5Yg==
+SHA512:
+  metadata.gz: !binary |-
+    NzNlNDhmYzg0YTgzOGY0ZTE5MTJiYmM3YzQwMDk1YzQxNTZhNWJiMmQ3MDNh
+    MjFkMTI1ZTExYjI4ZWQzZGI3MjYxMWE4MmQ2NmJiMWFmY2JjNTdmYTBkOTkz
+    YWNmMjU3ODAyN2I0M2FlMTYzYTY4ODA4MDQxMmNhMDA2ZGVkMGY=
+  data.tar.gz: !binary |-
+    NmMzZDZkZjQ5ODZlZTFmN2FiNWM0NWI2MTdmODI5YzA0YWJjZGRhOTg0Nzlm
+    YWEyODBmYThlNmM1NTY1ZTkxZjM4MmY3NTFlODIzZDUwZDkzYzRlMTEzZjc1
+    Y2QxNjA2ODgwOTExNmFmZGY1ZWI2NjViZTFiN2FjMDQ5NjkxOTk=

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Ngan Pham
+
+MIT License
+
+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.md

@@ -0,0 +1,171 @@
+# Walmart Open
+
+[Walmart Open](https://developer.walmartlabs.com) is Walmart's official products search and ordering API. There are actually two distinct API endpoints: one for product search and lookup and one for ordering.
+
+## Products API
+
+To use the Products API, you must register for a Walmart Open account and obtain an API key. You can also API calls from their [interacive API tool](https://developer.walmartlabs.com/io-docs).  For documentation can be found here: https://developer.walmartlabs.com/docs.
+
+## Commerce API
+
+As of right now, the Commerce API is [only available to select partners](https://developer.walmartlabs.com/forum/read/162059).  Once you've established a relationship with them, you will need the following to access the Commerce API:
+- API Key
+- API Secret
+- Generated Private/Public Key for message signing. You will need to give them your public key before proceeding.
+- A billing record id; Provided to you by Walmart when you give them your public key.
+- A [walmart.com](http://www.walmart.com) account that is connected to your Walmart Open account.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'walmart_open'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install walmart_open
+
+## Usage
+
+### Configuring the Client
+```ruby
+require "walmart_open"
+
+client = WalmartOpen::Client.new do |config|
+  ## Product API
+  config.product_api_key = "GggS6aPxDteRCyRxYnqz9bPp"
+
+  # This value defaults to 5.
+  config.product_calls_per_second = 4
+
+  ## Commerce API
+  config.commerce_api_key = "7XQLSmhqTXJHQ5xdGG7ZUh8d"
+  config.commerce_api_secret = "Mm5BX4c7QC"
+  config.commerce_private_key = File.read("/path/to/your/private/key/file")
+
+  # This value defaults to 2.
+  config.commerce_calls_per_second = 1
+
+  # Set this to true for development mode.
+  # This mainly applies to the Commerce API; orders will not actually be placed.
+  config.debug = true
+end
+```
+
+### Making Product API Calls
+```ruby
+# Search
+res = client.search("ipod")
+#=> SearchResults
+# example of res
+# res.query = "ipod"
+# res.total = 53259
+# res.start = 1
+# res.page = ?
+# res.items = [ Item_1, Item_2 ....]
+
+# Lookup (by item id)
+item = client.lookup(15076191)
+#=> Item
+# when success: example of item
+# item.error? == false
+# item.id = "15076191"
+# item.name = "Apple iPod Touch 4th Generation 32GB with Bonus Accessory Kit"
+# item.price = "189.0"
+# item.upc = nil
+# item.category_node = "3944_96469_164001"
+# item.short_description = "The world's most popular portable gaming device ... "
+# item.long_description = "<br><b>Apple iPod touch 32GB (4th Gen) ..."
+# item.brand = nil
+# item.shipping_rate = 0.0
+# item.size = nil
+# item.color = "Black"
+# item.model_number = ?
+# item.url =  "http://www.walmart.com/ip/Apple-iPod-Touch-8GB-32GB-and-64GB-newest-model/15076191"
+# item.raw_attributes = {"itemId" => 15076191, .....}
+
+# when fail: example of item
+# item.error? == true
+# item.error[:code] = 4002
+# item.error[:message] = "Invalid itemId"
+# item.raw_attributes = {"errors"=>[{"code"=>4002, "message"=>"Invalid itemId"}]}
+
+# Taxonomy
+taxonomies = client.taxonomy
+#=> Array
+# when success, example of one of taxonomies
+# taxonomies.categories = {"id"=>"5438", "name"=>"Apparel", "path"=>"Apparel", "children"=>[{"id"=>"5438_426265",
+  "name"=>"Accessories", "path"=>"Apparel/Accessories", "children"=>[{"id"=>"5438_426265_1043621",
+  "name"=>"Bandanas", "path"=>"Apparel/Accessories/Bandanas"}, ...]]}
+```
+
+### Making Commerce API Calls
+```ruby
+# Placing an Order
+order = WalmartOpen::Order.new({billing_id: 1, first_name: "James",
+                               last_name: "Fong", partner_order_id: "38",
+                               partner_order_time: "16:15:47"})
+# required fields:
+# billing_id: long, first_name: string
+# optional fields:
+# last_name: string
+# partner_order_time: string in format of HH:MM:SS, default to Time.now
+# partner_order_id: string, default to "Order-#{HASH_OF_RAND_AND_ORDER_TIME}"
+
+order.add_shipping_address({street1: "200 Blossom Ln", street2: "100 Flynn Avenue", city: "Mountain View", state: "CA", zipcode: "94043", country: "USA"})
+# required:
+# street1: string, city: string, state: string, zipcode: string, country: string
+# optional:
+# street2: string
+
+# add_item method 1, add_item(item_id, item_price, shipping_price = nil, quantity = 1)
+order.add_item(10371356, 5, 22.94)
+order.add_item(25174174, 214.99)
+
+# add_item method 2, add_item(item, quantity = 1)
+order.add_item(client.lookup(10371356))
+order.add_item(client.lookup(25174174))
+
+# order.valid? == true
+
+res = client.order(order)
+#=> OrderResults
+# when order succeeds, we see res as example below
+# res.error? = true
+# res.order_id = "2677911409503"
+# res.partner_order_id = "13"
+# res.items = [ ordered_item, ...]
+# res.total =  "237.96"  # sum of ordered_item.price for all ordered_items
+# res.sales_tax = "20.82"
+# res.surcharge = "0.0"
+# res.raw_attributes = {"response"=>{"orderId"=>"2677914395453", "partnerOrderId"=>"41", "items"=>{"item"=>{"itemId"=>"10371356", "quantity"=>"1", "itemPrice"=>"22.97"}}, "total"=>"29.95", "itemTotal"=>"22.97", "shipping"=>"4.97", "salesTax"=>"2.01", "surcharge"=>"0.00"}}
+
+# Note that order_item have class OrderedItem. As an example
+# ordered_item.id = 25174174
+# ordered_item.quantity = 1
+# ordered_item.price = 214.99
+# ordered_item.raw_attributes = {"itemId"=>"25174174", "quantity"=>"1", "itemPrice"=>"214.99"}
+
+# when order fails, we see res as below
+# res.error? == true
+# res.error = {:code=>"10001", :message=>"Invalid xml"}
+# res.error[:code] = "10001"
+# res.error[:message] = "Invalid xml"
+# res.raw_attributes = {"errors"=>{"error"=>{"code"=>"10001", "message"=>"Invalid xml"}}}
+```
+
+### Authentication failure
+In the case of authentication failure during an API call, a
+WalmartOpen::AuthenticationError exception will be raised
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/walmart_open.rb

@@ -0,0 +1,6 @@
+require "walmart_open/version"
+require "walmart_open/client"
+require "walmart_open/errors"
+
+module WalmartOpen
+end

data/lib/walmart_open/auth_token.rb

@@ -0,0 +1,25 @@
+module WalmartOpen
+  class AuthToken
+    BUFFER_TIME = 30 # seconds
+
+    attr_reader :token_type,
+                :access_token,
+                :time,
+                :expiration_time
+
+    def initialize(attrs, grant_time = Time.now)
+      @expiration_time = grant_time + attrs["expires_in"]
+      @token_type = attrs["token_type"]
+      @access_token = attrs["access_token"]
+      @time = grant_time
+    end
+
+    def expired?
+      Time.now + BUFFER_TIME >= expiration_time
+    end
+
+    def authorization_header
+      "#{token_type.capitalize} #{access_token}"
+    end
+  end
+end

data/lib/walmart_open/client.rb

@@ -0,0 +1,48 @@
+require "walmart_open/config"
+require "walmart_open/connection_manager"
+require "walmart_open/requests/search"
+require "walmart_open/requests/lookup"
+require "walmart_open/requests/taxonomy"
+require "walmart_open/requests/token"
+require "walmart_open/requests/place_order"
+
+module WalmartOpen
+  class Client
+    attr_reader :connection
+    attr_reader :config
+    attr_reader :auth_token
+
+    def initialize(config_attrs = {})
+      @config = Config.new(config_attrs)
+      @connection = ConnectionManager.new(self)
+
+      yield config if block_given?
+    end
+
+    def search(query, params = {})
+      connection.request(Requests::Search.new(query, params))
+    end
+
+    def lookup(item_id, params = {})
+      connection.request(Requests::Lookup.new(item_id, params))
+    end
+
+    def taxonomy
+      connection.request(Requests::Taxonomy.new)
+    end
+
+    def order(order_info)
+      authenticate!
+
+      connection.request(Requests::PlaceOrder.new(order_info))
+    end
+
+    private
+
+    def authenticate!
+      if !@auth_token || @auth_token.expired?
+        @auth_token = connection.request(Requests::Token.new)
+      end
+    end
+  end
+end

data/lib/walmart_open/commerce_request.rb

@@ -0,0 +1,23 @@
+require "walmart_open/request"
+
+module WalmartOpen
+  class CommerceRequest < Request
+    private
+
+    def request_method
+      :post
+    end
+
+    def build_url(client)
+      url = "https://#{client.config.commerce_domain}"
+      url << "/#{client.config.commerce_version}"
+      url << "/qa" if client.config.debug
+      url << "/#{path}"
+      url << params_to_query_string(build_params(client))
+    end
+
+    def parse_response(response)
+      OrderResults.new(response.parsed_response)
+    end
+  end
+end

data/lib/walmart_open/config.rb

@@ -0,0 +1,41 @@
+require "uri"
+
+module WalmartOpen
+  class Config
+    attr_accessor :debug,
+                  :product_domain,
+                  :product_version,
+                  :product_api_key,
+                  :product_calls_per_second,
+                  :commerce_domain,
+                  :commerce_version,
+                  :commerce_api_key,
+                  :commerce_api_secret,
+                  :commerce_private_key,
+                  :commerce_private_key_password,
+                  :commerce_calls_per_second
+
+    def initialize(options = {})
+      # Default to production mode.
+      self.debug = false
+
+      # Set some defaults for Product API.
+      self.product_domain    = "walmartlabs.api.mashery.com"
+      self.product_version   = "v1"
+      self.product_calls_per_second = 5
+
+      # Set some defaults for Commerce API.
+      self.commerce_domain  = "api.walmartlabs.com"
+      self.commerce_version = "v1"
+      self.commerce_calls_per_second = 2
+
+      options.each do |key, value|
+        public_send("#{key}=", value)
+      end
+    end
+
+    def private_key
+      @private_key ||= OpenSSL::PKey.read(commerce_private_key, commerce_private_key_password)
+    end
+  end
+end

data/lib/walmart_open/connection_manager.rb

@@ -0,0 +1,47 @@
+module WalmartOpen
+  class ConnectionManager
+    def initialize(client)
+      @client = client
+      @calls = {}
+    end
+
+    def request(request_obj)
+      throttle(request_obj) do
+        request_obj.submit(@client)
+      end
+    end
+
+    private
+
+    def throttle(request_obj)
+      type = request_type(request_obj)
+      @calls[type] ||= []
+      calls = @calls[type]
+
+      now = Time.now
+      calls.delete_if { |time| now.to_f - time.to_f >= 1 }
+
+      if calls.size >= calls_per_second(type)
+        sleep((calls.first + 1) - now)
+      end
+
+      ret_val = yield
+
+      calls << Time.now
+
+      ret_val
+    end
+
+    def request_type(request_obj)
+      case request_obj
+        when ProductRequest  then :product
+        when CommerceRequest then :commerce
+        else raise "Unknown request type"
+      end
+    end
+
+    def calls_per_second(type)
+      @client.config.public_send("#{type}_calls_per_second")
+    end
+  end
+end

data/lib/walmart_open/errors.rb

@@ -0,0 +1,13 @@
+module WalmartOpen
+  class WalmartOpenError < ::StandardError
+  end
+
+  class AuthenticationError < WalmartOpenError
+  end
+
+  class ItemNotFoundError < WalmartOpenError
+  end
+
+  class OrderError < WalmartOpenError
+  end
+end

data/lib/walmart_open/item.rb

@@ -0,0 +1,41 @@
+module WalmartOpen
+  class Item
+    API_ATTRIBUTES_MAPPING = {
+      "itemId" => "id",
+      "name" => "name",
+      "salePrice" => "price",
+      "upc" => "upc",
+      "categoryNode" => "category_node",
+      "shortDescription" => "short_description",
+      "longDescription" => "long_description",
+      "branchName" => "brand",
+      "standardShipRate" => "shipping_rate",
+      "size" => "size",
+      "color" => "color",
+      "modelNumber" => "model_number",
+      "productUrl" => "url",
+      "availableOnline" => "available_online"
+    }
+
+    API_ATTRIBUTES_MAPPING.each_value do |attr_name|
+      attr_reader attr_name
+    end
+
+    attr_reader :raw_attributes
+
+    def initialize(attrs)
+      @raw_attributes = attrs
+      extract_known_attributes
+    end
+
+    private
+
+    def extract_known_attributes
+      API_ATTRIBUTES_MAPPING.each do |api_attr, attr|
+        next unless raw_attributes.has_key?(api_attr)
+
+        instance_variable_set("@#{attr}", raw_attributes[api_attr])
+      end
+    end
+  end
+end