retailigence_ruby 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c402bae87c9588519c02a8854a8fda6c3d1cc539
+  data.tar.gz: db26dab02b2f714a992e690fefd75caf6613426a
+SHA512:
+  metadata.gz: f9217ceddba1ff48fde254d1d8adaf4855ad1189ea1c1a390ef1dc5d6ea6f26f09d2230dfc5cb86da0d71e4f0393c7c8df0daa09af5858b4ee5491ec8d5fc26a
+  data.tar.gz: 048892f901ad61f3155cfe7c864b0cb7db1d3bd22e5b25590b99193f90fc67cd3e3b504f0dac669edc8c1639587b646ed509fea45da0d68fcb43f49bb5417fb5

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in retailigence_ruby.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Drew Tempelmeyer
+
+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,81 @@
+# Retailigence
+
+Ruby library for interacting with [Retailigence](http://retailigence.com) API v2.1.
+
+**NOTE:** You'll need an API key from Retailigence. You can [request one from here](http://www.retailigence.com/developers/request-key/).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'retailigence_ruby'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install retailigence_ruby
+
+## Configuring
+
+Configuration only needs to be defined once.
+
+```
+Retailigence.configure do |config|
+	config.api_key = 'your-api-key'
+	# config.production = false # Uncomment this line if you want to use the test environment
+end
+```
+
+If you're using Rails, it's recommended you place the above code in an initializer such as `config/initializers/retailigence.rb`.
+
+## Searching Products
+
+Searching products will return a `SearchResult` with a collection of `Retailigence::Product` for the results. See the `Product` model for available attributes and methods.
+
+```
+search_results = Retailigence::Product.search(
+	userlocation: '37.3323,-122.0312',
+	requestorid: 'test',
+	name: 'Xbox One'
+)
+
+search_results.each do |product|
+	puts product.name
+end
+
+# => "Xbox One - Console"
+# => "FIFA 2014 (Xbox One)"
+```
+
+## Searching Locations
+
+Searching locations will return a `SearchResult` with a collection of `Retailigence::Retailer` for the results. Locations are embedded within the retailer and can be accessed by calling `retailer.locations`. See the `Retailer` and `Location` models available attributes and methods.
+
+```
+search_results = Retailigence::Location.search(
+	userlocation: '37.3323,-122.0312',
+	requestorid: 'test',
+	keywords: 'Best Buy'
+)
+
+search_results.each do |retailer|
+	puts retailer.name
+	puts retailer.locations
+end
+
+# => "Best Buy"
+# => #<Retailigence::Location>
+# => #<Retailigence::Location>
+```
+	
+
+## Contributing
+
+1. Fork it ( https://github.com/drewtempelmeyer/retailigence_ruby/fork )
+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,25 @@
+require 'bundler/gem_tasks'
+require 'rdoc/task'
+require 'rake/testtask'
+require 'rubocop/rake_task'
+
+Rubocop::RakeTask.new(:rubocop)
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/test_*.rb'
+  test.verbose = false
+end
+
+task :console do
+  require 'irb'
+  require 'irb/completion'
+  require 'retailigence_ruby' # You know what to do.
+  ARGV.clear
+  IRB.start
+end
+
+RDoc::Task.new do |rdoc|
+  rdoc.main = 'README.md'
+  rdoc.rdoc_files.include('README.md', 'lib/**/*.rb')
+end

data/lib/retailigence.rb

@@ -0,0 +1,33 @@
+require 'retailigence/version'
+require 'retailigence/configuration'
+require 'retailigence/exceptions'
+require 'retailigence/model'
+require 'retailigence/search_result'
+require 'retailigence/product'
+require 'retailigence/distance'
+require 'retailigence/location'
+require 'retailigence/retailer'
+require 'retailigence/address'
+require 'retailigence/image'
+require 'retailigence/inventory'
+
+module Retailigence
+  # Retailigence's API Version
+  API_VERSION = '2.1'
+
+  class << self
+    # Stores the current Retailigence Configuration
+    attr_accessor :configuration
+
+    # Configure Retailigence. See Configuration for available configuration options
+    #
+    # === Example
+    #   Retailigence.configure do |config|
+    #     config.api_key = 'your-retailigence-api-key'
+    #   end
+    def configure
+      @configuration ||= Configuration.new
+      yield @configuration
+    end
+  end
+end

data/lib/retailigence/address.rb

@@ -0,0 +1,14 @@
+module Retailigence #:nodoc:
+  # Represents an address returned from Retailigence. The address is normally
+  # embedded within a Location object.
+  #
+  # === Attributes
+  # * <tt>address1</tt> - The street address of the Location
+  # * <tt>city</tt> - The city of the Location
+  # * <tt>state</tt> - The state of the Location
+  # * <tt>postal</tt> - The postal code (ZIP code) of the Location
+  # * <tt>country</tt> - The country of the Location
+  class Address < Model
+    attributes :address1, :city, :state, :postal, :country
+  end
+end

data/lib/retailigence/configuration.rb

@@ -0,0 +1,26 @@
+module Retailigence #:nodoc:
+  # Configure Retailigence with your credentials.
+  #
+  # === Example
+  #   Retailigence.configure do |config|
+  #     config.api_key = 'yourapikeyhere'
+  #     config.production = false # Use the test route
+  #   end
+  class Configuration
+    # The API key issued to you by Retailigence
+    attr_accessor :api_key
+
+    # Wether or not to use the production Retailigence API
+    attr_writer :production
+
+    # Returns true if using the production API
+    def production?
+      @production == true
+    end
+
+    # Returns true if using the test API
+    def test?
+      !production?
+    end
+  end
+end

data/lib/retailigence/distance.rb

@@ -0,0 +1,11 @@
+module Retailigence #:nodoc:
+  # Representation of the distance from the <tt>userlocation</tt> and the
+  # respective Product or Location
+  #
+  # === Attributes
+  # * <tt>distance</tt> - A float value based on the distance <tt>units</tt>
+  # * <tt>units</tt> - String of distance measurement. Example: "miles", "meters", etc.
+  class Distance < Model
+    attributes :distance, :units
+  end
+end

data/lib/retailigence/exceptions.rb

@@ -0,0 +1,5 @@
+module Retailigence #:nodoc:
+  # Raised when Retailigence has not yet be configured.
+  # See Retailigence::configure.
+  class NotConfigured < StandardError; end
+end

data/lib/retailigence/image.rb

@@ -0,0 +1,10 @@
+module Retailigence #:nodoc:
+  # A product image returned by the API
+  #
+  # === Attributes
+  # * <tt>image_name</tt> - The image name. Normally either "IMAGESMALL" or "IMAGELARGE"
+  # * <tt>link</tt> - The URL of the image
+  class Image < Model
+    attributes :imageName, :link
+  end
+end

data/lib/retailigence/inventory.rb

@@ -0,0 +1,33 @@
+module Retailigence #:nodoc:
+  # Retrieve the inventory for a product at a specific location.
+  #
+  # === Attributes
+  # * <tt>product_id</tt> - The Product#id
+  # * <tt>retailer_id</tt> - The Retailer#id
+  # * <tt>location_id</tt> - The Location#id
+  # * <tt>price</tt> - The price
+  # * <tt>currency</tt> - The price's respective currency
+  # * <tt>quantity</tt> - Number of items in stock
+  # * <tt>quantity_text</tt> - Detail about the current stock
+  # * <tt>product_name</tt> - The Product#name
+  class Inventory < Model
+    attributes :product_id, :retailer_id, :location_id, :price, :currency,
+      :quantity, :quantityText, :productName
+
+    # Retrieve the inventory information for the provided <tt>product_id</tt>
+    # and <tt>location_id</tt>
+    #
+    # === Returns
+    # Inventory
+    def self.fetch(product_id = nil, location_id = nil)
+      params = {
+        productId: product_id,
+        locationId: location_id
+      }
+
+      results = get('inventory', params)['RetailigenceAPIResult']['results']
+
+      Inventory.new(results.first['ProductLocation'])
+    end
+  end
+end

data/lib/retailigence/location.rb

@@ -0,0 +1,61 @@
+module Retailigence #:nodoc:
+  # A location result from the Retailigence API
+  #
+  # === Attributes
+  # * <tt>id</tt> - Unique identifier for the location
+  # * <tt>timezone</tt> - Timezone of the location
+  # * <tt>distance</tt> - Distance object calculated based off the <tt>userlocation</tt> param
+  # * <tt>phone</tt> - Location's phone number
+  # * <tt>t_nav_link</tt> - URL to get directions from your current position to the location's position
+  # * <tt>location</tt> - Contains the latitude and longitude for the location. Using the <tt>latitude</tt> and <tt>longitude</tt> attributes are preferred
+  # * <tt>address</tt> - An Address object containing the physical postal address
+  # * <tt>hours</tt> - Colon separated operating hours
+  # * <tt>map_link</tt> - Google Maps URL for the location's address
+  # * <tt>name</tt> - Name of the location
+  # * <tt>retailer</tt> - Retailer
+  # * <tt>retlocationid</tt> - External location ID provided by the Retailer
+  # * <tt>latitude</tt> - The location's latitude
+  # * <tt>longitide</tt> - The location's longitude
+  class Location < Model
+    attributes :id, :timezone, :distance, :phone, :tNavLink, :location,
+      :address, :hours, :mapLink, :name, :retailer, :retlocationid, :latitude,
+      :longitude
+
+    # Search locations and retailers based on the <tt>params</tt> passed.
+    #
+    # === Params
+    # See the documentation from Retailigence for all possible parameters
+    #
+    # === Returns
+    # SearchResult with <tt>results</tt> being an array of Retailer
+    def self.search(params = {})
+      results = get('locations', params)
+
+      retailers = results['RetailigenceAPIResult']['results'].map do |result|
+        Retailer.new(result['Retailer'])
+      end
+
+      SearchResult.new(retailers)
+    end
+
+    def retailer=(retailer) #:nodoc:
+      @retailer = Retailer.new(retailer)
+    end
+
+    def distance=(distance) #:nodoc:
+      @distance = Distance.new(distance)
+    end
+
+    def address=(address) #:nodoc:
+      @address = Address.new(address)
+    end
+
+    # Convert the locations hash to latitude and longitude
+    def location=(location) #:nodoc:
+      @latitude  = location['latitude']
+      @longitude = location['longitude']
+      @location  = location
+    end
+
+  end
+end

data/lib/retailigence/model.rb

@@ -0,0 +1,84 @@
+require 'typhoeus'
+require 'json'
+
+module Retailigence #:nodoc:
+  # The base for all API requests and models throughout the Retailigence library.
+  class Model
+    # Initialize an object with the provided <tt>params</tt>. For the available
+    # <tt>params</tt>, see the model's <tt>Attributes</tt>.
+    def initialize(params = {})
+      params.each do |key, value|
+        mapped_key = underscore(key)
+        send("#{mapped_key}=".to_sym, value) if safe_attribute?(mapped_key)
+      end
+    end
+
+    class << self
+      # Attributes safe for initialization
+      attr_accessor :safe_attributes
+
+      # Creates a list of safe attributes for assign using #initialize.
+      def attributes(*attrs)
+        @safe_attributes ||= []
+
+        attrs.each do |attr_name|
+          name = underscore(attr_name.to_s).to_sym
+
+          attr_accessor name
+          @safe_attributes << name
+        end
+      end
+
+      # Perform a request using Typhoeus.
+      #
+      # === Arguments
+      # * <tt>method</tt> - Symbol for the request method.
+      # * <tt>action</tt> - The path to request
+      # * <tt>params</tt> - Hash of params to send with the request
+      def request(method = :get, action = nil, params = {})
+        params[:apikey] = Retailigence.configuration.api_key
+        params[:format] = 'JSON'
+
+        url = "http://#{host}/v#{Retailigence::API_VERSION}/#{action}"
+
+        response = Typhoeus.send(method, url, params: params)
+        JSON.parse response.body
+      end
+
+      # Convenience method for performing a GET request. See #request
+      def get(action = nil, params = {})
+        request(:get, action, params)
+      end
+
+      # Convert the camelCase to its underscore/snake_case equivalent.
+      def underscore(word)
+        word.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .tr('-', '_').downcase
+      end
+
+      private
+
+      def host
+        host =
+          if Retailigence.configuration.production?
+            'api'
+          else
+            'apitest'
+          end
+
+        "#{host}.retailigence.com"
+      end
+    end
+
+    private
+
+    def underscore(word)
+      self.class.underscore(word.to_s).to_sym
+    end
+
+    def safe_attribute?(key)
+      self.class.safe_attributes.include?(key)
+    end
+  end
+end