shopsense-ruby 0.1.0

data/lib/shopsense.rb

@@ -0,0 +1,24 @@
+require 'net/http'
+require 'yajl'
+=begin rdoc
+Shopsense is an easy to use Ruby interface for the {Shopstyle API}[https://shopsense.shopstyle.com/page/ShopSenseHome],
+also known a ShopSense.  The ShopStyle API is a free service from ShopStyle that pays you for sending traffic 
+to online retailers from your blog, website, or application.
+
+The ShopStyle API allows client applications to retrieve the underlying data for all the basic elements of the 
+ShopStyle websites, including products, brands, retailers, categories, and looks. For ease of development, 
+the API is a REST-style web service, composed of simple HTTP GET requests. Data is returned to the client in 
+either XML or JSON formats. The API is client-language independent and easy to use from PHP, Java, JavaScript, 
+or any other modern development context.
+
+Shopsense provides a number of helpful classes and methods for integrating data aquired from the ShopStyle API into
+your application.
+
+== Roadmap
+* If you think you found a bug in Shopsense see DEVELOPERS@Bugs
+* If you want to use Shopsense to interface with the ShopStyle API
+  see Shopsense::API
+=end
+
+require 'shopsense/client'
+require 'shopsense/api'

data/lib/shopsense/api.rb

@@ -0,0 +1,200 @@
+module Shopsense
+
+  class API < Client
+
+    # Searches the shopsense API
+    # @param [String] search_string
+    #   The string to be in the query.
+    # @param  [Integer] index
+    #   The start index of results returned.
+    # @param  [Integer] num_results
+    #   The number of results to be returned.
+    # @return  A list of Product objects. Each Product has an id, name, 
+    #   description, price, retailer, brand name, categories, images in small/medium/large, 
+    #   and a URL that forwards to the retailer's site.
+    def search( search_string = nil, index = 0, num_results = 10)
+      raise "no search string provieded!" if( search_string === nil)
+
+      fts   = "fts="    + search_string.split().join( '+').to_s
+      min   = "min="    + index.to_s
+      count = "count="  + num_results.to_s
+      args  = [fts, min, count].join( '&')
+
+      return call_api( __method__, args)
+    end
+
+
+    # This method returns a list of categories and product counts that describe the results 
+    # of a given product query. The query is specified using the product query parameters.
+    # @param  [String]  search_string The string to be in the query.
+    # @return [String]  A list of Category objects. Each Category has an id, name, and count 
+    #   of the number of query results in that category.
+    def get_category_histogram( search_string = nil)
+      raise "no search string provieded!" if( search_string === nil)
+
+      fts = "fts=" + search_string.split().join( '+').to_s
+
+      return call_api( __method__, fts)
+    end
+
+    # This method returns a list of categories and product counts that describe the results 
+    # of a given product query. The query is specified using the product query parameters.
+    # @param  [String]  filter_type
+    #   The type of filter data to return. Possible values are 
+    #   Brand, Retailer, Price, Discount, Size and Color.
+    # @param  [String]  search_string The string to be in the query.
+    # @return [String]  A list of Category objects. Each Category has an id, name, and count 
+    #   of the number of query results in that category.
+    def get_filter_histogram( filter_type = nil, search_string = nil)
+      raise "no search string provieded!" if( search_string === nil)
+      raise "invalid filter type" if( !self.filter_types.include?( filter_type))
+
+      filterType = "filterType=" + filter_type.to_s
+      fts = "fts=" + search_string.split().join( '+').to_s
+      args  = [filterType, fts].join( '&')
+
+      return call_api( __method__, args)
+    end
+
+    # This method returns a list of brands that have live products. Brands that have 
+    # very few products will be omitted.
+    # @return [String] A list of all Brands, with id, name, url, and synonyms of each.
+    def get_brands
+      return call_api( __method__)
+    end
+
+    # This method returns information about a particular look and its products.
+    # @param [Integer] look_id 
+    #   The ID number of the look. An easy way to get a look's ID is 
+    #   to go to the Stylebook page that contains the look at the ShopStyle website and 
+    #   right-click on the button that you use to edit the look. From the popup menu, select 
+    #   "Copy Link" and paste that into any text editor. The "lookId" query parameter of that 
+    #   URL is the value to use for this API method.
+    # @return [String]  single look, with title, description, a set of tags, and a list of products. 
+    #   The products have the fields listed (see #search)
+    def get_look( look_id = nil)
+      raise "no look_id provieded!" if( look_id === nil)
+
+      look = "look=" + look_id.to_s
+
+      return call_api( __method__, look)
+    end
+
+    # This method returns a list of retailers that have live products.
+    # @return [Sting] A list of all Retailers, with id, name, and url of each.
+    def get_retailers
+      return call_api( __method__)
+    end
+
+    # This method returns information about a particular user's Stylebook, the 
+    # looks within that Stylebook, and the title and description associated with each look.
+    # @param [String] username
+    #   The username of the Stylebook owner.
+    # @param  [Integer] index
+    #   The start index of results returned.
+    # @param  [Integer] num_results
+    #   The number of results to be returned.
+    # @return [String] 
+    #   A look id of the user's Stylebook, the look id of each individual look within that Stylebook, 
+    #   and the title and description associated with each look.
+    def get_stylebook(  user_name = nil, index = 0, num_results = 10)
+      raise "no user_name provieded!" if( user_name === nil)
+      
+      handle  = "handle=" + user_name.to_s
+      min     = "min="    + index.to_s
+      count   = "count="  + num_results.to_s
+      args    = [handle, min, count].join( '&')
+
+      return call_api( __method__, args)
+    end
+
+    # This method returns information about looks that match different kinds of searches.
+    # @param [Integer] look_type
+    #   The type of search to perform. Supported values are:
+    #   New - Recently created looks.
+    #   TopRated - Recently created looks that are highly rated.
+    #   Celebrities - Looks owned by celebrity users.
+    #   Featured - Looks from featured stylebooks.
+    # @param [String] username
+    #   The username of the Stylebook owner.
+    # @param  [Integer] index
+    #   The start index of results returned.
+    # @param  [Integer] num_results
+    #   The number of results to be returned.
+    # @return [String] 
+    #   A list of looks of the given type.
+    def get_looks( look_type = nil, index = 0, num_results = 10)
+      raise "invalid filter type must be one of the following: #{self.look_types}" if( !self.look_types.include?( look_type))
+
+      type    = "type="   + look_type.to_s
+      min     = "min="    + index.to_s
+      count   = "count="  + num_results.to_s
+      args    = [type, min, count].join( '&')
+
+      return call_api( __method__, args)
+    end
+
+    # TODO:
+    # This method does not return a reponse of XML or JSON data like the other elements of the API. 
+    # Instead, it forwards the user to the retailer's product page for a given product. It is the 
+    # typical behavior to offer when the user clicks on a product. The apiSearch method returns URLs 
+    # that call this method for each of the products it returns.
+    # @param [Integer]
+    #   The ID number of the product. An easy way to get a product's ID is to find the product somewhere 
+    #   in the ShopStyle UI and right-click on the product image. From the popup menu, select "Copy Link" 
+    #   ("Copy link location" or "Copy shortcut" depending on your browser) and paste that into any text 
+    #   editor. The "id" query parameter of that URL is the value to use for this API method.
+    # @return [String]
+    #   A web link to the retailer. $1 of the $0
+    def visit_retailer( id)
+
+    end
+
+    # This method returns the popular brands for a given category along with a sample product for the 
+    # brand-category combination.
+    # @param [String] category 
+    #   Category you want to restrict the popularity search for. This is an optional 
+    #   parameter. If category is not supplied, all the popular brands regardless of category will be returned.
+    # @return [String] A list of trends in the given category. Each trend has a brand, category, url, and 
+    #   optionally the top-ranked product for each brand/category.
+    def get_trends( category = "", products = 0)
+      cat = "cat=" + category.to_s
+      products = "products=" + products.to_s
+      args    = [cat, products].join( '&')
+
+      return call_api( __method__, args)
+    end
+    private
+
+      # This method is used for making the http calls building off the DSL of this module.
+      # @param [String] method
+      #   The method which is to be used in the call to Shopsense
+      # @param [String] args
+      #   A concatenated group of arguments seperated by a an & symbol and spces substitued with a + symbol.
+      # @return [String] A list of the data returned
+      def call_api( method, args = nil)
+        method_url  = self.api_url  + self.send( "#{method}_path")
+        pid         = "pid="        + self.partner_id
+        format      = "format="     + self.format
+        site        = "site="       + self.site
+
+        if( args === nil) then
+          uri   = URI.parse( method_url.to_s + [pid, format, site].join('&').to_s) 
+        else
+          uri   = URI.parse( method_url.to_s + [pid, format, site, args].join('&').to_s) 
+        end
+
+        return Net::HTTP.get( uri)
+      end
+  end
+end
+
+    # @macro [new] api.index
+    #   @param [Integer] index
+    #     The start index of results returned.
+    # @macro [new] api.num_results
+    #   @param [Integer] num_results
+    #     The number of results to be returned.
+    # @macro [new] api.search_string
+    #   @param [String] search_string
+    #     The string to be in the query.

data/lib/shopsense/client.rb

@@ -0,0 +1,43 @@
+module Shopsense
+  class Client
+    def initialize( args = { })
+      raise "No partner_id" if( !args.has_key?( 'partner_id'))
+
+      attr_accessors = {
+                #:
+                'format'  => 'json', 
+                'site'    => 'us'}
+      attr_accessors.each_key{ |key| (class << self; self; end).send( :attr_accessor, key.to_sym)}
+
+      attr_readers = {
+                'partner_id'                  => nil, 
+                'api_url'                     => 'http://api.shopstyle.com',
+                'search_path'                 => '/action/apiSearch?',
+                'get_brands_path'             => '/action/apiGetBrands?',
+                'get_look_path'               => '/action/apiGetLook?',
+                'get_looks_path'              => '/action/apiGetLooks?',
+                'get_retailers_path'          => '/action/apiGetRetailers?',
+                'get_stylebook_path'          => '/action/apiGetStylebook?',
+                'visit_retailers_path'        => '/action/apiVisitRetailer?',
+                'get_trends_path'             => '/action/apiGetTrends?',
+                'get_category_histogram_path' => '/action/apiGetCategoryHistogram?',
+                'get_filter_histogram_path'   => '/action/apiGetFilterHistogram?',
+                'filter_types'                => ['Brands', 'Retailer', 'Price', 'Discount', 'Size', 'Color'],
+                'look_types'                  => ['New', 'TopRated', 'Celebrities', 'Featured'],
+                'formats'                     => ['xml', 'json', 'json2', 'jsonvar', 'jsonvar2', 'jsonp', 'rss'],
+                'sites'                       => ['www.shopstyle.com', 'www.shopstyle.co.uk']}
+      attr_readers.each_key{ |key| (class << self; self; end).send( :attr_reader, key.to_sym)}
+
+      attr_writers = {}
+      attr_writers.each_key{ |key| (class << self; self; end).send( :attr_writer, key.to_sym)}
+
+      attrs = attr_accessors.merge( attr_readers).merge( attr_writers)
+      attrs.each_key do |key| 
+        attrs[ key] = args[ key] if( args.has_key?( key))
+      end
+
+      attrs.each {|key, value| instance_variable_set( "@#{key}", value)}
+    end
+  end
+
+end

data/lib/shopsense/version.rb

@@ -0,0 +1,8 @@
+module Shopsense
+    major = 0
+    minor = 1
+    tiny  = 0
+    #pre   = ""
+
+    VERSION = [major, minor, tiny].compact.join('.')
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: shopsense-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Kurt Rudolph
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70300918516620 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :development
+  prerelease: false
+  version_requirements: *70300918516620
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: &70300918514760 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: *70300918514760
+description: This Gem provides an easy to use interface for the ShopStyleAPI commonly
+  known as ShopSense. ShopSense-Ruby includes a set of convent classes and methods
+  designed to make accessing the ShopStyle API from your Ruby application seamless.
+email:
+- ShopSense-Ruby.RubyGems@RudyIndustries.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/shopsense/api.rb
+- lib/shopsense/client.rb
+- lib/shopsense/version.rb
+- lib/shopsense.rb
+homepage: http://RudyIndustries.GitHub.com/shopsense-ruby
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: ShopSense API! For Ruby! So Great.
+test_files: []
+has_rdoc: