skimlinks 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3e74941ec6e62b0229bfd956be8cfa643d4d4f02
-  data.tar.gz: ca029f6b9c348538b3298f8a893cf767c0455e5c
+  metadata.gz: 5d176c89122667e84f50c2a3e4aadc7e7b308fec
+  data.tar.gz: 8f2a3b4dfedc721dd626adcd4f67659d5496d621
 SHA512:
-  metadata.gz: 020fe91831e6054caa63c00da23493843f2bb35511a228daf90e976ade1dda5e87025ae7ae4cbef6812fcfc2152021806cea9dd77c30d36df4631bdc3ec787e5
-  data.tar.gz: f65b5b136dd0d69566ad5b576e4c106e1322f520b456487b6572380a09a0aa77adb9a886688b34b7aed2f94cfdf383dcc3011b949bfb5c78713f81074212d223
+  metadata.gz: bb8c3bafe621d4f58ceb6536350a40b390ab81ac347703d861931fa0d3ca652651545fedd379a3bfee8f0ed9be202dafe932be94cf63fcf6505fee678b907cc9
+  data.tar.gz: d5609beacaba2147aaa5d63c453b91576a226953430e958ead5e1b2cbf54117650d4e71bfef2a930322f1594be803b63d0763753c8b49a66e11e66dcf3626c7a

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2012 kraut computing UG (haftungsbeschränkt)
+Copyright (c) 2013 kraut computing UG (haftungsbeschränkt)
 
 MIT License
 

data/README.md

@@ -1,5 +1,193 @@
 # Skimlinks
 
-This gem is no longer public.
+[![Gem Version](https://badge.fury.io/rb/skimlinks.png)](http://badge.fury.io/rb/skimlinks)
+[![Build Status](https://secure.travis-ci.org/krautcomputing/skimlinks.png)](http://travis-ci.org/krautcomputing/skimlinks)
+[![Dependency Status](https://gemnasium.com/krautcomputing/skimlinks.png)](https://gemnasium.com/krautcomputing/skimlinks)
+[![Code Climate](https://codeclimate.com/github/krautcomputing/skimlinks.png)](https://codeclimate.com/github/krautcomputing/skimlinks)
 
-If you want to use it, please get in touch via info@krautcomputing.com
+A simple wrapper around the [Skimlinks APIs](http://skimlinks.com/apis)
+
+Read the accompanying [blog post](http://www.krautcomputing.com/blog/2013/01/11/new-gem-skimlinks/).
+
+## Requirements
+
+Requires Ruby 1.9.2 or higher
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'skimlinks'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install skimlinks
+
+## APIs
+
+Skimlinks offers the following APIs:
+
+* The [Product API](http://api-products.skimlinks.com/doc/) to search for products and product categories
+* The [Merchant API](http://api-merchants.skimlinks.com/doc/) to search for merchants and merchant categories
+* The [Link API](http://go.redirectingat.com/doc/) to convert regular URLs into affiliate URLs
+* The [Reporting API](https://api-reports.skimlinks.com/doc/) to receive a history of your earned commissions
+
+This gem currently only implements access to the Product API and Merchant API.
+
+## Usage
+
+### Configuration
+
+Add configurations to `config/initializers/skimlinks.rb`:
+
+```ruby
+Skimlinks.configure do |config|
+  config.api_key   = 'foobar'       # Your API key (get it here: https://accounts.skimlinks.com/productapi) (mandatory)
+  config.cache     = Rails.cache    # Set to an instance of ActiveSupport::Cache::Store to cache the API requests. (optional, defaults to nil)
+  config.format    = :json          # Currently no other setting is supported. In the future it will be possible to set this to :xml to communicate with the API via XML. (optional, defaults to :json)
+  config.cache_ttl = 10.minutes     # Set to higher/lower value to cache requests shorter/longer. (optional, defaults to 1 day)
+end
+```
+
+### Product API
+
+#### Get a list of product categories
+
+```ruby
+Skimlinks::ProductSearch.new.categories
+
+=> {
+=>   "Animals"                                                      => 1, # Category name => category ID
+=>   "Animals > Live Animals"                                       => 2,
+=>   "Animals > Pet Supplies"                                       => 3,
+=>   "Animals > Pet Supplies > Bird Supplies"                       => 4,
+=>   "Animals > Pet Supplies > Bird Supplies > Bird Cages & Stands" => 5,
+=>   "Animals > Pet Supplies > Bird Supplies > Bird Food"           => 6,
+=>   ...
+=> }
+```
+
+#### Get a nested list of product categories
+
+```ruby
+Skimlinks::ProductSearch.new.nested_categories
+
+=> {
+=>   "Animals" => {
+=>     "Live Animals" => nil,
+=>     "Pet Supplies" => {
+=>       "Bird Supplies" => {
+=>         "Bird Cages & Stands" => nil,
+=>         "Bird Food"           => nil,
+=>         ...
+=>       }
+=>     }
+=>   }
+=> }
+```
+
+#### Search for products
+
+```ruby
+Skimlinks::ProductSearch.new(
+  query:       'justin bieber', # Search query                                               (mandatory)
+  page:        1,               # Page                                                       (optional, defaults to 1)
+  rows:        10,              # Number of rows to return                                   (optional, max. 300, defaults to 10)
+  min_price:   100,             # Minimum price (including decimal digits, i.e. 100 = $1.00) (optional)
+  max_price:   500,             # Maximum price (including decimal digits, i.e. 500 = $5.00) (optional)
+  country:     'uk',            # Restrict search to products of a specific country          (optional)
+  merchant_id: 8286,            # Restrict search to products of a specific merchant         (optional)
+  category:    'Toys & Games'   # Restrict search to products of a specific category         (optional)
+).products
+
+=> [
+=>   #<Skimlinks::Product:0x007ff694913fb0 @description="Justin Bieber (Boyfriend)", @name="Justin Bieber Boyfriend Poster", @currency="gbp", @product_id="8286|33428272", @id="8116651", @merchant_id=8286, @price=219, @url="http://www.play.com/Product.aspx?r=GADG&title=33428272", @category="Toys & Games", @image_urls=[#<URI::HTTP:0x007ff694910540 URL:http://images.productserve.com/preview/1418/569238291.jpg>], @country="UK", @merchant_name="Play.com">,
+=>   #<Skimlinks::Product:0x007ff694cb98e0 @description="Justin Bieber (Live) Poster", @name="Justin Bieber (Live) Poster", @currency="gbp", @product_id="8286|20468288", @id="7979941", @merchant_id=8286, @price=219, @url="http://www.play.com/Product.aspx?r=GADG&title=20468288", @category="Toys & Games", @image_urls=[#<URI::HTTP:0x007ff694cb9cc8 URL:http://images.productserve.com/preview/1418/153122801.jpg>], @country="UK", @merchant_name="Play.com">,
+=>   #<Skimlinks::Product:0x007ff694f60fd0 @description="Justin Bieber (Hoodie) Mini Poster", @name="Justin Bieber (Hoodie) Mini Poster", @currency="gbp", @product_id="8286|20418241", @id="7975531", @merchant_id=8286, @price=219, @url="http://www.play.com/Product.aspx?r=GADG&title=20418241", @category="Toys & Games", @image_urls=[#<URI::HTTP:0x007ff694f610c0 URL:http://images.productserve.com/preview/1418/148546541.jpg>], @country="UK", @merchant_name="Play.com">,
+=>   ...
+=> ]
+```
+
+### Merchant API
+
+#### Search for merchants
+
+```ruby
+Skimlinks::MerchantSearch.new(
+  category_ids: [1, 2, 3] # Return only merchants in the specificed categories (optional)
+).merchants
+
+=> [
+=>   #<Skimlinks::Merchant:0x00000103d33b60 @id=17738, @name="*NEW!* High Commission Payout!", @preferred={}, @updated_at=2012-12-16 01:02:00 +0100, @average_conversion_rate="0", @average_commission="0", @logo_url="http://s.skimresources.com/logos/17738.jpg", @domains={"9682"=>"mykegelsecret.com", "45143"=>"kegelmasters.com"}, @categories={"37"=>"health & beauty", "1"=>"adult & mature", "38"=>"health & beauty;cosmetics", "39"=>"health & beauty;health products"}, @countries=["united states"], @product_count=0>,
+=>   #<Skimlinks::Merchant:0x00000103cd7428 @id=41004, @name="Adultsextoys.com - A Huge Range Of Adult Products", @preferred={}, @updated_at=2012-12-16 01:02:00 +0100, @average_conversion_rate="0", @average_commission="0", @logo_url="http://s.skimresources.com/logos/41004.jpg", @domains={"40457"=>"adultsextoys.com.au"}, @categories={"1"=>"adult & mature"}, @countries=["australia"], @product_count=0>,
+=>   #<Skimlinks::Merchant:0x00000103cb2dd0 @id=68079, @name="Adultshop", @preferred={}, @updated_at=2012-12-16 01:02:00 +0100, @average_conversion_rate="0", @average_commission="0", @logo_url="http://s.skimresources.com/logos/68079.jpg", @domains={"68133"=>"shop.adultshop.de"}, @categories={"1"=>"adult & mature"}, @countries=["germany"], @product_count=0>,
+=>   ...
+=> ]
+```
+
+#### Get a single merchant
+
+```ruby
+Skimlinks::MerchantSearch.new.merchant(
+ 12678 # Merchant ID, get it from calling Skimlinks::MerchantSearch.merchants first (mandatory)
+)
+
+=> #<Skimlinks::Merchant:0x00000105204f30 @id=12678, @name="Amazon US", @preferred={"commission"=>"8.5% General products\r\n4% Electronics", "commissionDetails"=>"Was 6% --&gt; NOW 8.5% General products!\r\nWas 3% --&gt; NOW 4% Electronics!", "description"=>"Amazon.com is the global leader in e-commerce.  They launch new product categories and stores around the world as it offers customers greater selection, lower prices, more in-stock merchandise, and a best-in-class shopping experience.", "ecpc"=>"0.00", "featured_commission"=>nil, "pp_enabled"=>"1"}, @updated_at=2012-12-07 01:02:00 +0100, @average_conversion_rate="5.42%", @average_commission="6.36%", @logo_url="http://s.skimresources.com/logos/12678.jpeg", @domains={"6309"=>"amazon.com", "47172"=>"wireless.amazon.com", "119814"=>"amazonsupply.com"}, @categories={"12"=>"consumer electronics;mobiles, pdas & satnav", "50"=>"phones, tv & broadband subscriptions", "8"=>"consumer electronics", "9"=>"consumer electronics;audio, tv & home theatre", "10"=>"consumer electronics;cameras & photos", "11"=>"consumer electronics;gadgets & geeks", "13"=>"consumer electronics;mp3 players & accessories", "18"=>"fashion & accessories", "19"=>"fashion & accessories;belts & bags", "20"=>"fashion & accessories;children's clothing", "21"=>"fashion & accessories;jewelry", "22"=>"fashion & accessories;lingerie & sleepwear", "23"=>"fashion & accessories;men's clothing", "24"=>"fashion & accessories;shoes", "25"=>"fashion & accessories;women's clothing", "33"=>"gifts", "34"=>"gifts;chocolate", "35"=>"gifts;flowers", "36"=>"gifts;novelty", "40"=>"home & garden", "41"=>"home & garden;bed & bath", "42"=>"home & garden;diy", "43"=>"home & garden;furniture & interior design", "44"=>"home & garden;garden", "45"=>"home & garden;home appliances", "37"=>"health & beauty", "38"=>"health & beauty;cosmetics", "39"=>"health & beauty;health products"}, @countries=["united states"], @product_count=0>
+```
+
+#### Get a list of merchant categories
+
+```ruby
+Skimlinks::MerchantSearch.new.categories
+
+=> {
+=>   "adult & mature"                                  => 1, # Category name => category ID
+=>   "arts, crafts & hobbies"                          => 2,
+=>   "automotive, cars & bikes"                        => 3,
+=>   "baby & parenting supplies"                       => 4,
+=>   "books & magazines"                               => 5,
+=>   "charities & non-profit"                          => 6,
+=>   "computers & software"                            => 7,
+=>   "consumer electronics"                            => 8,
+=>   "consumer electronics > audio, tv & home theatre" => 9,
+=>   "consumer electronics > cameras & photos"         => 10,
+=>   ...
+=> }
+```
+
+#### Get a nested list of merchant categories
+
+```ruby
+Skimlinks::MerchantSearch.new.nested_categories
+
+=> {
+=>   "adult & mature"            => nil,
+=>   "arts, crafts & hobbies"    => nil,
+=>   "automotive, cars & bikes"  => nil,
+=>   "baby & parenting supplies" => nil,
+=>   "books & magazines"         => nil,
+=>   "charities & non-profit"    => nil,
+=>   "computers & software"      => nil,
+=>   "consumer electronics"      => {
+=>     "audio, tv & home theatre"  => nil,
+=>     "cameras & photos"          => nil,
+=>     ...
+=>   }
+=> }
+```
+
+## TODO
+
+* Implement access to Link API and Reporting API
+
+## 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/lib/skimlinks.rb

@@ -1,4 +1,24 @@
+require 'gem_config'
+require 'active_support/cache'
+
 module Skimlinks
+  include GemConfig::Base
+
+  ApiError          = Class.new(StandardError)
+  InvalidParameters = Class.new(StandardError)
+
+  with_configuration do
+    has :api_key, classes: String
+    has :format, values: :json, default: :json
+    has :cache, classes: ActiveSupport::Cache::Store
+    has :cache_ttl, classes: Numeric, default: 1.day
+  end
 end
 
 require 'skimlinks/version'
+require 'skimlinks/client'
+require 'skimlinks/merchant'
+require 'skimlinks/product'
+require 'skimlinks/search_helpers'
+require 'skimlinks/merchant_search'
+require 'skimlinks/product_search'

data/lib/skimlinks/client.rb

@@ -0,0 +1,208 @@
+require 'json'
+require 'rest-client'
+require 'mechanize'
+
+module Skimlinks
+  class Client
+    API_ENDPOINTS = {
+      product_api:  'http://api-product.skimlinks.com/',
+      merchant_api: 'http://api-merchants.skimlinks.com/merchants/',
+      link_api:     'http://go.productwidgets.com/'
+    }
+
+    attr_accessor *Skimlinks.configuration.rules.keys
+
+    def initialize(args = {})
+      config = Skimlinks.configuration.current.merge(args)
+
+      Skimlinks.configuration.rules.keys.each do |key|
+        self.send "#{key}=", config[key]
+      end
+
+      @product_api  = RestClient::Resource.new(API_ENDPOINTS[:product_api])
+      @merchant_api = RestClient::Resource.new(API_ENDPOINTS[:merchant_api])
+      @mechanize    = Mechanize.new do |m|
+        m.agent.redirect_ok      = false
+        m.agent.http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+    end
+
+    # Product API
+
+    def product_search(args)
+      product_count_and_products(args).last
+    end
+
+    def product_count(args)
+      product_count_and_products(args.merge(rows: 0)).first
+    end
+
+    def product_categories
+      @product_categories ||= product_api('categories')['skimlinksProductAPI']['categories']
+    end
+
+    # Merchant API
+
+    def merchant_categories
+      @merchant_categories ||= merchant_api('categories')
+    end
+
+    def merchant_category_ids
+      @merchant_category_ids ||= flatten(self.merchant_categories).grep(/^\d+$/).uniq.map(&:to_i)
+    end
+
+    def merchants_in_category(category_id)
+      [].tap do |merchants|
+        start, found = 0, nil
+
+        while found.nil? || start < found
+          data = merchant_api('category', category_id, 'limit', 200, 'start', start)
+
+          merchants.concat data['merchants'] if data['merchants'].present?
+
+          start = data['numStarted'].to_i + data['numReturned'].to_i
+          found = data['numFound']
+        end
+      end
+    end
+
+    def merchant_search(query, preferred = false)
+      [].tap do |merchants|
+        start, found = 0, nil
+
+        while found.nil? || start < found
+          data = merchant_api('search', query, 'limit', 200, 'start', start, preferred ? '?filter_by=preferred' : nil)
+
+          merchants.concat data['merchants'] if data['merchants'].present?
+
+          start = data['numStarted'].to_i + data['numReturned'].to_i
+          found = data['numFound']
+        end
+      end
+    end
+
+    # Link API
+
+    def affiliate(url, publisher_id)
+      link_api url, publisher_id
+    end
+
+    private
+
+    def flatten(object)
+      case object
+      when Hash
+        object.to_a.map { |v| flatten(v) }.flatten
+      when Array
+        object.flatten.map { |v| flatten(v) }
+      else
+        object
+      end
+    end
+
+    def returning_json(&block)
+      JSON.parse block.call
+    end
+
+    def returning_xml(&block)
+      Nokogiri::XML block.call
+    end
+
+    def product_count_and_products(args)
+      api_query = []
+      api_query << %(id:(#{args[:ids].join(' ')}))                                                          if args[:ids].present?
+      api_query << %((#{%w(title description).map { |field| %(#{field}:"#{args[:query]}") }.join(' OR ')})) if args[:query].present?
+      api_query << %(price:[#{args[:min_price].presence || '*'} TO #{args[:max_price].presence || '*'}])    if args[:min_price].present? || args[:max_price].present?
+      api_query << %(categoryId:(#{args[:category_ids].join(' ')}))                                         if args[:category_ids].present?
+      api_query << %(merchantId:"#{args[:merchant_id]}")                                                    if args[:merchant_id].present?
+      api_query << %(country:"#{args[:country]}")                                                           if args[:country].present?
+      api_query << %(currency:"#{args[:currency]}")                                                         if args[:currency].present?
+
+      # TODO: Check for categoryId 0, '' or nil, missing categoryId
+
+      query_params = {
+        q: api_query.join(' AND ')
+      }
+      query_params[:rows]  = args[:rows]  if args[:rows].present?
+      query_params[:start] = args[:start] if args[:start].present?
+
+      product_data = product_api('query', query_params)['skimlinksProductAPI']
+
+      [product_data['numFound'], product_data['products']]
+    end
+
+    def get(api, path, params = {})
+      raise Skimlinks::InvalidParameters, 'Only JSON format is supported right now.' unless Skimlinks.configuration.format == :json
+
+      do_get = lambda do
+        returning_json do
+          api[URI.escape(path)].get params: params
+        end
+      end
+
+      if Skimlinks.configuration.cache.nil?
+        do_get.call
+      else
+        cache_key = [
+          'skimlinks',
+          'api',
+          Digest::MD5.hexdigest(api.to_s + path + params.to_s)
+        ].join(':')
+        cache_options = Skimlinks.configuration.cache_ttl > 0 ? { expires_in: Skimlinks.configuration.cache_ttl } : {}
+        Skimlinks.configuration.cache.fetch cache_key, cache_options do
+          do_get.call
+        end
+      end
+    rescue RestClient::Exception => e
+      message = [e.message].tap do |message_parts|
+        error = JSON.parse(e.response)['skimlinksProductAPI']['message'] rescue nil
+        message_parts << error if error.present?
+      end.join(' - ')
+      raise Skimlinks::ApiError, message
+    end
+
+    def product_api(method, params = {})
+      raise Skimlinks::InvalidParameters, 'API key not configured' if Skimlinks.configuration.api_key.blank?
+
+      params = params.reverse_merge(
+        format: Skimlinks.configuration.format,
+        key:    Skimlinks.configuration.api_key
+      )
+
+      get(@product_api, method, params).tap do |response|
+        raise Skimlinks::InvalidParameters, 'API key is invalid' if response.is_a?(Array) && response.first =~ /^Invalid API key/
+      end
+    end
+
+    def merchant_api(method, *params)
+      raise Skimlinks::InvalidParameters, 'API key not configured' if Skimlinks.configuration.api_key.blank?
+
+      path = [
+        Skimlinks.configuration.format,
+        Skimlinks.configuration.api_key,
+        method,
+        *params.compact
+      ].join('/')
+
+      get(@merchant_api, path).tap do |response|
+        raise Skimlinks::InvalidParameters, 'API key is invalid' if response.is_a?(Array) && response.first =~ /^Invalid API key/
+      end
+    end
+
+    def link_api(url, publisher_id)
+      query_params = { url: CGI.escape(url), id: publisher_id, xs: 1 }
+      path         = [API_ENDPOINTS[:link_api], URI.encode_www_form(query_params)].join('?')
+      response     = @mechanize.head(path)
+
+      raise Skimlinks::ApiError, "Unexpected response code: #{response.code}" unless response.code == '302'
+
+      redirect_location = response['location']
+      case redirect_location
+      when url, %r(http://www\.google\.com/search\?q=)
+        nil
+      else
+        redirect_location
+      end
+    end
+  end
+end

data/lib/skimlinks/merchant.rb

@@ -0,0 +1,35 @@
+require 'active_support/hash_with_indifferent_access'
+
+module Skimlinks
+  class Merchant
+    attr_accessor :id, :name, :preferred, :updated_at, :average_conversion_rate, :average_commission, :logo_url, :domains, :categories, :countries, :product_count
+
+    class << self
+      def build_from_api_response(merchant_data)
+        merchant_data.map do |merchant|
+          self.new \
+            id:                      merchant['merchantID'].to_i,
+            name:                    merchant['merchantName'].presence,
+            preferred:               HashWithIndifferentAccess.new(merchant['preferred']),
+            updated_at:              merchant['dateUpdated'].present? ? Time.parse(merchant['dateUpdated']) : nil,
+            average_conversion_rate: merchant['averageConversionRate'].presence,
+            average_commission:      merchant['averageCommission'].presence,
+            logo_url:                merchant['logo'].presence,
+            domains:                 HashWithIndifferentAccess.new(merchant['domains']),
+            categories:              HashWithIndifferentAccess.new(merchant['categories']),
+            countries:               Array(merchant['countries'].presence)
+        end.sort_by(&:name)
+      end
+    end
+
+    def initialize(args = {})
+      args.each do |k, v|
+        self.send "#{k}=", v
+      end
+    end
+
+    def preferred?
+      self.preferred.present?
+    end
+  end
+end