bol 0.0.1.beta

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/CHANGELOG.md

@@ -0,0 +1 @@
+(unreleased)

data/Gemfile

@@ -0,0 +1,2 @@
+source "http://rubygems.org"
+gemspec

data/Guardfile

@@ -0,0 +1,7 @@
+guard 'rspec', version: 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+  watch('spec/support.rb')      { "spec" }
+end
+

data/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (C) 2011 by Arjan van der Gaag
+
+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,170 @@
+# Bol
+
+A Ruby wrapper around the [bol.com developers API][docs], that will be made
+available as a Gem. *Currently in beta stage.*
+
+[docs]: http://developers.bol.com
+
+## Installation
+
+Bol is a simple Ruby gem, so it requires a working installation of Ruby with
+Ruby gems.  Ruby 1.9 is required. Install the gem:
+
+```
+$ gem install bol
+```
+
+Or, if your project uses [Bundler][] simply add it to your `Gemfile`:
+
+[Bundler]: http://gembundler.com
+
+```ruby
+gem 'bol'
+```
+
+Then, simply `require` it in your code, provide some configuration settings and
+query away.
+
+## Available operations
+
+Here are the currently working operations:
+
+### Loading a specific product
+
+If you know an ID, you can load a product directly:
+
+```ruby
+product = Bol::Product.find(params[:id])
+product.title
+product.cover(:medium)
+product.referral_url('my_associate_id')
+```
+
+### Listing products
+
+You can get a list of popular or bestselling products:
+
+* `Bol.top_products`
+* `Bol.top_products_overall`
+* `Bol.top_products_last_week`
+* `Bol.top_products_last_two_months`
+* `Bol.new_products`
+* `Bol.preorder_products`
+
+Or, you can apply a scope to limit results to a category:
+
+```ruby
+Bol::Scope.new(params[:category_id]).top_producs
+```
+
+### Searching products
+
+You can search globally for keywords or ISBN and use a Arel-like syntax
+for setting options:
+
+```ruby
+Bol.search(params[:query]).limit(10).offset(10).order('sales_ranking ASC')
+Bol.search(params[:query]).page(params[:page])
+```
+
+You can scope your search to a specific category:
+
+```ruby
+Bol::Scope.new(params[:category_id]).search(params[:query])
+```
+
+### Loading categories and refinements
+
+Loading all top-level categories (e.g. `DVDs` or `English Book`) is simple
+enough:
+
+```ruby
+categories = Bol.categories
+categories.first.name # => 'Books'
+```
+
+You can load subsequent subcategories:
+
+```ruby
+Bol::Scope.new(categories.first.id).categories
+```
+
+Refinements (e.g. 'under 10 euros') work much the same way as categories, but
+are grouped under a shared name, such as group 'Price' with refinements 'up to
+10 euros', '10 to 20 euros', etc.:
+
+```ruby
+groups = Bol.refinements
+group = groups.first
+group.name # => 'Price'
+group.refinements.first.name # => 'under 10 euros'
+```
+
+### Scoping operations
+
+The `Bol::Scope` object limits results to given categories and/or refinements.
+You can create a scope using explicit IDs, and you can do basic combinations:
+
+```ruby
+books = Bol::Scope.new(some_category_id)
+cheap = Bol::Scope.new(some_refinement_id)
+(books + cheap).top_products
+```
+
+Here's an overview of all the operations that should still be implemented:
+
+## Background
+
+The available operations map almost directly to operations provided by the API
+to search, load lists of products or load a single product by ID. I do aim to
+a add a little sugar to make working with Ruby objects a little easier:
+
+* Add `page` helper method to combine `limit` and `offset`
+* Scope operations by category in a ActiveRecord association style
+* Delay API calls until explicitly requested or triggered by looping over
+  results
+
+## Wishlist
+
+* Allow scoping by category or refinement objects instead of just IDs
+* Add a simple identiy map, so the same product does not have to be loaded
+  twice when requested twice
+* Properly differentiate between product types. Currently built around books;
+  DVDs, music and toys may or may not work as expected.
+* Add default ordering of products
+
+I do not need this stuff myself, but I will gladly take pull requests for such
+features.
+
+## Configuration
+
+To be allowed to make requests to the Bol.com API you need to register on their
+site and request a access key and secret. Configure the Bol gem as follows:
+
+```ruby
+Bol.configure do |c|
+  c.key = 'your public access key'
+  c.secret = 'your private secret'
+  c.per_page = 10
+end
+```
+
+## Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version
+  unintentionally.
+* Commit, do not mess with rakefile, version, or history. (if you want to have
+  your own version, that is fine but bump version in a commit by itself I can
+  ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+## History
+
+For a full list of changes, please see CHANGELOG.md
+
+## License
+
+Copyright (C) 2011 by Arjan van der Gaag. Published under the MIT license. See
+LICENSE.md for details.

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bol.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path('../lib', __FILE__)
+require 'bol/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'bol'
+  s.version     = Bol::VERSION
+  s.authors     = ['Arjan van der Gaag']
+  s.email       = ['arjan@arjanvandergaag.nl']
+  s.homepage    = "https://github.com/avdgaag/bol"
+  s.summary     = %q{Simple Ruby wrapper around the bol.com developer API}
+  s.description = %q{Access the bol.com product catalog from a Ruby project. You can search products, list top selling products and find product information for individual catalog items.}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ['lib']
+
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'guard-rspec'
+  s.add_development_dependency 'rb-fsevent'
+  s.add_development_dependency 'growl'
+  s.add_development_dependency 'fakeweb'
+end

data/lib/bol.rb

@@ -0,0 +1,52 @@
+require 'bol/version'
+
+module Bol
+  autoload :Scope,            'bol/scope'
+  autoload :Configuration,    'bol/configuration'
+  autoload :Product,          'bol/product'
+  autoload :Query,            'bol/query'
+  autoload :Request,          'bol/request'
+  autoload :Requests,         'bol/requests'
+  autoload :Parser,           'bol/parser'
+  autoload :Parsers,          'bol/parsers'
+  autoload :Proxy,            'bol/proxy'
+  autoload :Category,         'bol/category'
+  autoload :Refinement,       'bol/refinement'
+  autoload :RefinementGroup,  'bol/refinement_group'
+  autoload :Signature,        'bol/signature'
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.reset_configuration
+    @configuration = nil
+  end
+
+  def self.configure(options = nil)
+    @configuration = Configuration.new(options)
+    yield @configuration if options.nil?
+  end
+
+  class << self
+    %w{
+      top_products
+      top_products_overall
+      top_products_last_week
+      top_products_last_two_months
+      new_products
+      preorder_products
+      search
+      categories
+      refinements
+    }.each do |name|
+      define_method name do |*args|
+        Scope.new.send(name, *args)
+      end
+    end
+  end
+
+  def find(id)
+    Bol::Product.find(id)
+  end
+end

data/lib/bol/category.rb

@@ -0,0 +1,5 @@
+module Bol
+  class Category
+    attr_accessor :name, :id, :count
+  end
+end

data/lib/bol/configuration.rb

@@ -0,0 +1,55 @@
+module Bol
+  ConfigurationError = Class.new(Exception)
+
+  class Configuration
+    ALLOWED_KEYS = %w[access_key secret per_page].map(&:to_sym)
+    REQUIRED_KEYS = %w[access_key secret].map(&:to_sym)
+
+    def initialize(options = {})
+      unless options.nil? || options.respond_to?(:each_pair)
+        raise ArgumentError, 'options should be Hash-like object'
+      end
+
+      @options = { per_page: 10 }
+
+      unless options.nil?
+        options.each_pair do |k, v|
+          self[k] = v
+        end
+      end
+    end
+
+    def [](key)
+      @options[key]
+    end
+
+    def []=(key, value)
+      unless ALLOWED_KEYS.include?(key)
+        raise ArgumentError, "#{key} is not a valid key"
+      end
+
+      @options[key] = value
+    end
+
+    def validate
+      REQUIRED_KEYS.each { |key| @options.fetch(key) }
+    rescue KeyError
+      raise Bol::ConfigurationError
+    end
+
+    def method_missing(name, *args)
+      return super unless respond_to? name
+      if name.to_s =~ /=$/
+        send(:[]=, name.to_s.sub(/=$/, '').to_sym, *args)
+      else
+        send(:[], name)
+      end
+    end
+
+    def respond_to?(name)
+      super or
+        ALLOWED_KEYS.include?(name) or
+        ALLOWED_KEYS.include?(name.to_s.sub(/=$/, '').to_sym)
+    end
+  end
+end

data/lib/bol/parser.rb

@@ -0,0 +1,34 @@
+require 'rexml/document'
+require 'ostruct'
+
+module Bol
+  class Parser
+    attr_reader :request
+
+    def initialize(request)
+      @request = request
+    end
+
+    def objects
+      [].tap do |collection|
+        xml.elements.each(xpath) do |el|
+          collection << parse_object(el)
+        end
+      end
+    end
+
+  protected
+
+    def underscorize(str)
+      str.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+    end
+
+    def camelize(str)
+      str.split('_').map(&:capitalize).join('')
+    end
+
+    def xml
+      @xml ||= REXML::Document.new(request.fetch.body)
+    end
+  end
+end

data/lib/bol/parsers.rb

@@ -0,0 +1,7 @@
+module Bol
+  module Parsers
+    autoload :Products,    'bol/parsers/products'
+    autoload :Categories,  'bol/parsers/categories'
+    autoload :Refinements, 'bol/parsers/refinements'
+  end
+end

data/lib/bol/parsers/categories.rb

@@ -0,0 +1,17 @@
+module Bol
+  module Parsers
+    class Categories < Parser
+      def xpath
+        '*/Category'
+      end
+
+      def parse_object(el)
+        Category.new.tap do |category|
+          category.name  = el.elements['Name'].text.strip
+          category.id    = el.elements['Id'].text.strip
+          category.count = el.elements['ProductCount'].text.strip.to_i
+        end
+      end
+    end
+  end
+end

data/lib/bol/parsers/products.rb

@@ -0,0 +1,34 @@
+require 'time'
+
+module Bol
+  module Parsers
+    class Products < Parser
+      def xpath
+        '*/Product'
+      end
+
+      def parse_object(el)
+        Product.new.tap do |product|
+          %w[id title subtitle type publisher short_description long_description ean rating binding_description language_code language_description].each do |field|
+            _field = camelize(field)
+            if el.elements[_field]
+              product.attributes[field.to_sym] = el.elements[_field].text.gsub(/\n\s+/, ' ').strip
+            end
+          end
+          product[:url] = el.elements['Urls'].elements['Main'].text.strip
+          if el.elements['ReleaseDate']
+            product[:release_date] = Time.parse(el.elements['ReleaseDate'].to_s)
+          end
+          product[:authors] = []
+          el.elements.each('Authors/Author') do |author|
+            product[:authors] << author.elements['Name'].text
+          end
+          product[:cover] = {}
+          el.elements['Images'].elements.each do |image|
+            product[:cover][underscorize(image.name).to_sym] = image.text.strip
+          end
+        end
+      end
+    end
+  end
+end