brickset_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e6b52a875ab697e5d7236fd7be4ff598d51af251db24f15ea5ce0545f1632784
+  data.tar.gz: cb26e22a5969958241a87c8296371fc11efa2a1210c618d172638a698692474f
+SHA512:
+  metadata.gz: 7ae116a2f2fd9d6bdd25d3c1839dc89511cdc8736f4f67ca8871632cba3a3f64c3d2a01ea1209fc2334ad8231a3dd9d57f4525c228558f2ca20fe0fd40aab7b2
+  data.tar.gz: 11339bb1026597277aef1b0280042d749692b32dae6765292b6169e9afae512edde14514f3604065b6efe5a464a18ac8b0657fe9ed0701bc8c23214b580bb011

data/.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.rspec
+.rspec_status
+.config
+.bundle
+*.gem
+Gemfile.lock
+doc/
+pkg/*
+docker
+coverage

data/.ruby-gemset

@@ -0,0 +1 @@
+brickset

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.5.1

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+script: rspec
+rvm:
+  - 2.5.1

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in brickset_api.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Kevin Tuhumury
+
+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,145 @@
+# Brickset
+
+[![Build Status](https://travis-ci.org/kevintuhumury/brickset.png?branch=master)](https://travis-ci.org/kevintuhumury/brickset)
+
+This gem provides a Ruby wrapper around the [Brickset](https://brickset.com) (v2) API, using HTTParty. Brickset is a library to access the Brickset API in an easy way. It wraps all of the methods, which are described in the [official documentation](https://brickset.com/tools/webservices/v2). The Brickset API by default responds with XML. This gem maps the XML responses to Ruby objects using HappyMapper.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'brickset_api', require: 'brickset'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install brickset_api
+
+### Apply for an API key
+
+You can retrieve an API key from the official Brickset [site](https://brickset.com/tools/webservices/requestkey). Just follow the instructions and once you've received the API key move on to the next step.
+
+### Configuration
+
+In order for you to use the Brickset gem, you'll need to configure the API key you've requested in the previous step. If you're using Rails, you could add the following to e.g. `config/initializers/brickset.rb`:
+
+```ruby
+Brickset.configure do |config|
+  config.api_key = '<API_KEY>'
+end
+```
+
+That's it. You're now ready to start using this gem.
+
+## Usage
+
+Using Brickset is easy. All you need to know is that all calls go through the `Brickset::Client` class. Most of the API calls provided by the Brickset v2 API require you to sign into Brickset in order for you to retrieve a token (which they call a `userHash`). This `token` can than be used to call the authenticated API calls and retrieve information of the signed in user.
+
+Now, you're not required to do so, but if you don't, you will only be able to retrieve generic information from the API. User specific information will not be accessible.
+
+### Create an instance of the Brickset client
+
+In order to retrieve data from the API, we'll need an instance of the Brickset client. So let's create it:
+
+```ruby
+client = Brickset.client
+```
+
+Yeah, that's it.
+
+### Create an instance of the Brickset client with access to authenticated API calls
+
+If you want to retrieve user specific information you'll need a token. You can retrieve one as follows:
+
+```ruby
+token = Brickset.login('<YOUR_USERNAME>', '<YOUR_PASSWORD>')
+```
+
+Now that you have access to the token, provide the client with it and you'll be good to go:
+
+```ruby
+client = Brickset.client(token: token)
+```
+
+That's it.
+
+### Helper methods
+
+There are two helper methods that you can use to check whether your API key and token are valid. Both of them will return a Boolean value. You can use them as follows:
+
+```ruby
+client.valid_api_key? # => true
+client.valid_token?   # => true
+```
+
+### Calling API methods
+
+Now, let's call our `sets` method with `Star Wars` (because its awesome, obviously) as a theme:
+
+```ruby
+sets = client.sets(theme: 'Star Wars')
+```
+
+The above call will return all sets that are in the `Star Wars` theme. As can be seen on the [API page](https://brickset.com/tools/webservices/v2) (look for `getSets`), there's a default limit of 20 records per page to retrieve. You could change that with the following:
+
+```ruby
+sets = client.sets(theme: 'Star Wars', page_size: 50)
+```
+
+Or navigate to the second page:
+
+```ruby
+sets = client.sets(theme: 'Star Wars', page_number: 2)
+```
+
+Let's say you're looking for the `Ultimate Collector Series` sets and more specifically the ones based on the `Millenium Falcon`. You can retrieve those with the following example:
+
+```ruby
+sets = client.sets(theme: 'Star Wars', subtheme: 'Ultimate Collector Series', query: 'Millenium Falcon')
+```
+
+At the time of writing this will result in two sets: `10179-1` from 2007 and `75192-1` from 2017. Let's say we want to select the last one to view its data:
+
+```ruby
+sets = client.sets(theme: 'Star Wars', subtheme: 'Ultimate Collector Series', query: 'Millenium Falcon')
+set  = sets.last           # => #<Brickset::Elements::Set:0x000055ad9ddfdd60 @set_id=26725, @number="75192", @number_variant=1, @name="Millennium Falcon", @year="2017", @description=nil, @category="Normal", @theme="Star Wars", @theme_group="Licensed", @subtheme="Ultimate Collector Series", @pieces="7541", @minifigs="8", @image=true, @image_url="https://images.brickset.com/sets/images/75192-1.jpg", @image_filename="75192-1", @thumbnail_url="https://images.brickset.com/sets/thumbs/tn_75192-1_jpg.jpg", @thumbnail_url_large="https://images.brickset.com/sets/small/75192-1.jpg", @brickset_url="https://brickset.com/sets/75192-1", @owned_by_total=5194, @wanted_by_total=4551, @released=true, @rating=5.0, @user_rating=4, @review_count=3, @instructions_count=2, @additional_image_count=61, @last_updated=Thu, 14 Sep 2017, @age_minimum=16, @age_maximum=nil, @notes=nil, @tags=nil, @retail_price_uk="649.99", @retail_price_us="799.99", @retail_price_ca="899.99", @retail_price_eu="799.99", @date_added_to_shop="2018-01-10", @date_removed_from_shop="", @packaging_type="Box", @height=0.0, @width=0.0, @depth=0.0, @weight=0.0, @availability="LEGO exclusive", @ean="", @upc="", @acm_data_count=0, @owned=true, @wanted=true, @number_owned=1, @user_notes="">
+
+set.id                     # => 26725
+set.pieces                 # => '7541'
+set.image_url              # => 'https://images.brickset.com/sets/images/75192-1.jpg'
+set.additional_image_count # => 61
+```
+
+You could now use `additional_images` to retrieve the 61 additional images from the above set. Simply supply the API call with the set ID:
+
+```ruby
+client.additional_images(set.id)
+
+# => [#<Brickset::Elements::AdditionalImage:0x000055ad9e0292b0 @thumbnail_url="https://images.brickset.com/sets/AdditionalImages/75192-1/tn_75192_1to1_jpg.jpg", @thumbnail_url_large=nil, @image_url="https://images.brickset.com/sets/AdditionalImages/75192-1/75192_1to1.jpg">, #<Brickset::Elements::AdditionalImage:0x000055ad9e027d98 @thumbnail_url="https://images.brickset.com/sets/AdditionalImages/75192-1/tn_75192_alt10_jpg.jpg", @thumbnail_url_large=nil, @image_url="https://images.brickset.com/sets/AdditionalImages/75192-1/75192_alt10.jpg">, ...]
+```
+
+It really is that easy. Need a specific method? Look for them in the `lib/brickset/api` directory.
+
+## Contributing
+
+You're very welcome to contribute to this gem. To do so, please follow these steps:
+
+1. Fork this project
+2. Clone your fork on your local machine
+3. Install the development dependencies with `bin/setup`
+4. Create your feature branch with `git checkout -b my-new-feature`
+5. Run the specs with `bundle exec rspec` and make sure everything is covered with RSpec
+6. Commit your changes `git commit -am 'Added new feature'`
+7. Push to your branch `git push origin my-new-feature`
+8. Create a new Pull Request
+
+You can run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Copyright
+
+Copyright 2018 Kevin Tuhumury. Released under the MIT License.

data/Rakefile

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

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'brickset'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require 'pry'
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/brickset.gemspec

@@ -0,0 +1,30 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'brickset/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'brickset_api'
+  spec.version       = Brickset::VERSION
+  spec.authors       = ['Kevin Tuhumury']
+  spec.email         = ['kevin.tuhumury@gmail.com']
+
+  spec.summary       = %q{A Ruby wrapper around the Brickset.com (v2) API.}
+  spec.description   = %q{This gem provides a Ruby wrapper around the Brickset.com (v2) API. The Brickset.com API responds with XML. This gem maps that into Ruby objects using Happymapper.}
+  spec.homepage      = 'https://github.com/kevintuhumury/brickset_api'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'httparty', '~> 0.16'
+  spec.add_runtime_dependency 'nokogiri-happymapper', '~> 0.8'
+  spec.add_runtime_dependency 'activemodel', '>= 5.2'
+
+  spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'webmock', '~> 3.4'
+  spec.add_development_dependency 'shoulda-matchers', '~> 3.1'
+end

data/lib/brickset.rb

@@ -0,0 +1,55 @@
+require 'httparty'
+require 'happymapper'
+require 'active_model'
+require 'active_support/all'
+
+require 'brickset/version'
+require 'brickset/configuration'
+
+require 'brickset/elements/set'
+require 'brickset/elements/year'
+require 'brickset/elements/theme'
+require 'brickset/elements/subtheme'
+require 'brickset/elements/instruction'
+require 'brickset/elements/additional_image'
+require 'brickset/elements/review'
+require 'brickset/elements/collection_detail'
+require 'brickset/elements/collection_total'
+require 'brickset/elements/minifig_collection'
+require 'brickset/elements/user_note'
+require 'brickset/elements/condition'
+
+require 'brickset/api/auth'
+require 'brickset/api/set'
+require 'brickset/api/collection/set'
+require 'brickset/api/collection/minifig'
+require 'brickset/api/collection/advanced'
+
+module Brickset
+  ValidationError = Class.new(StandardError)
+
+  BASE_URI = 'https://brickset.com/api/v2.asmx'.freeze
+
+  class << self
+    attr_accessor :configuration
+
+    def client(options = {})
+      Brickset::Client.new(options)
+    end
+
+    def login(username, password)
+      client.login(username, password)
+    end
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+    def reset
+      self.configuration = Configuration.new
+    end
+  end
+end
+
+require 'brickset/client'

data/lib/brickset/api/auth.rb

@@ -0,0 +1,22 @@
+module Brickset
+  module Api
+    module Auth
+
+      def login(username, password)
+        xml = call('/login', username: username, password: password)
+        HappyMapper.parse(xml).content
+      end
+
+      def valid_api_key?
+        xml = call('/checkKey')
+        HappyMapper.parse(xml).content == 'OK'
+      end
+
+      def valid_token?
+        xml = call('/checkUserHash')
+        HappyMapper.parse(xml).content != 'INVALID'
+      end
+
+    end
+  end
+end

data/lib/brickset/api/collection/advanced.rb

@@ -0,0 +1,34 @@
+module Brickset
+  module Api
+    module Collection
+      module Advanced
+        extend ActiveSupport::Concern
+
+        included do
+          attr_accessor :condition
+
+          with_options(on: :collection_detail_conditions) do |options|
+            options.validates :condition, inclusion: { in: %w(acquired now) }
+          end
+        end
+
+        def collection_detail(set_id)
+          xml = call('/getCollectionDetail', setID: set_id)
+          Brickset::Elements::CollectionDetail.parse(xml, single: true)
+        end
+
+        def collection_detail_conditions(condition)
+          self.condition = condition
+
+          if valid?(:collection_detail_conditions)
+            xml = call('/getCollectionDetailConditions', which: condition)
+            Brickset::Elements::Condition.parse(xml)
+          else
+            raise ValidationError, self.errors.full_messages.to_sentence
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/brickset/api/collection/minifig.rb

@@ -0,0 +1,35 @@
+module Brickset
+  module Api
+    module Collection
+      module Minifig
+        extend ActiveSupport::Concern
+
+        included do
+          attr_accessor :minifig_number, :number_owned, :wanted
+
+          with_options(on: :update_minifig_collection) do |options|
+            options.validates :minifig_number, :number_owned, :wanted, presence: true
+            options.validates :number_owned, inclusion: { in: (0..999) }
+            options.validates :wanted, inclusion: { in: [0, 1] }
+          end
+        end
+
+        def minifig_collection(query: '', owned: '', wanted: '')
+          xml = call('/getMinifigCollection', query: query, owned: owned, wanted: wanted)
+          Brickset::Elements::MinifigCollection.parse xml
+        end
+
+        def update_minifig_collection(options)
+          extract_attributes_from_options(options)
+
+          if valid?(:update_minifig_collection)
+            handle_update call('/setMinifigCollection', minifigNumber: minifig_number, qtyOwned: number_owned, wanted: wanted)
+          else
+            raise ValidationError, self.errors.full_messages.to_sentence
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/brickset/api/collection/set.rb

@@ -0,0 +1,117 @@
+module Brickset
+  module Api
+    module Collection
+      module Set
+        extend ActiveSupport::Concern
+
+        included do
+          attr_accessor :set_id, :number_owned, :wanted, :owned, :notes, :rating
+
+          with_options(on: :update_collection) do |options|
+            options.validates :set_id, :number_owned, :wanted, presence: true
+            options.validates :number_owned, inclusion: { in: (0..999) }
+            options.validates :wanted, inclusion: { in: [0, 1] }
+          end
+
+          with_options(on: :update_collection_owned) do |options|
+            options.validates :set_id, :owned, presence: true
+            options.validates :owned, inclusion: { in: [0, 1] }
+          end
+
+          with_options(on: :update_collection_wanted) do |options|
+            options.validates :set_id, :wanted, presence: true
+            options.validates :wanted, inclusion: { in: [0, 1] }
+          end
+
+          with_options(on: :update_collection_number_owned) do |options|
+            options.validates :set_id, :number_owned, presence: true
+            options.validates :number_owned, inclusion: { in: (0..999) }
+          end
+
+          with_options(on: :update_collection_user_notes) do |options|
+            options.validates :set_id, :notes, presence: true
+            options.validates :notes, length: { maximum: 200 }
+          end
+
+          with_options(on: :update_user_rating) do |options|
+            options.validates :set_id, :rating, presence: true
+            options.validates :rating, inclusion: { in: (0..5) }
+          end
+        end
+
+        def collection_totals
+          xml = call('/getCollectionTotals')
+          Brickset::Elements::CollectionTotal.parse(xml)
+        end
+
+        def update_collection(options)
+          extract_attributes_from_options(options)
+
+          if valid?(:update_collection)
+            handle_update call('/setCollection', setID: set_id, qtyOwned: number_owned, wanted: wanted)
+          else
+            raise ValidationError, self.errors.full_messages.to_sentence
+          end
+        end
+
+        def update_collection_owned(options)
+          extract_attributes_from_options(options)
+
+          if valid?(:update_collection_owned)
+            handle_update call('/setCollection_owns', setID: set_id, owned: owned)
+          else
+            raise ValidationError, self.errors.full_messages.to_sentence
+          end
+        end
+
+        def update_collection_wanted(options)
+          extract_attributes_from_options(options)
+
+          if valid?(:update_collection_wanted)
+            handle_update call('/setCollection_wants', setID: set_id, wanted: wanted)
+          else
+            raise ValidationError, self.errors.full_messages.to_sentence
+          end
+        end
+
+        def update_collection_number_owned(options)
+          extract_attributes_from_options(options)
+
+          if valid?(:update_collection_number_owned)
+            handle_update call('/setCollection_qtyOwned', setID: set_id, qtyOwned: number_owned)
+          else
+            raise ValidationError, self.errors.full_messages.to_sentence
+          end
+        end
+
+        def update_collection_user_notes(options)
+          extract_attributes_from_options(options)
+
+          if valid?(:update_collection_user_notes)
+            handle_update call('/setCollection_userNotes', setID: set_id, notes: notes)
+          else
+            raise ValidationError, self.errors.full_messages.to_sentence
+          end
+        end
+
+        def update_user_rating(options)
+          extract_attributes_from_options(options)
+
+          if valid?(:update_user_rating)
+            handle_update call('/setUserRating', setID: set_id, rating: rating)
+          else
+            raise ValidationError, self.errors.full_messages.to_sentence
+          end
+        end
+
+        def user_notes
+          xml = call('/getUserNotes')
+          Brickset::Elements::UserNote.parse(xml).reject do |user_note|
+            user_note.set_id.nil? && user_note.user_notes.nil?
+          end
+        end
+
+      end
+    end
+  end
+end