betterific 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+*.swp
+.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 betterific.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Brad Cater
+
+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,117 @@
+# Betterific
+
+This gem makes it easy to access the Betterific API to explore betterifs, tags,
+and users.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'betterific'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install betterific
+
+## Usage
+
+To get started quickly, you should use Betterific::Client, which uses
+Betterific::JsonClient in the absence of the
+[ruby-protocol-buffers](https://github.com/codekitchen/ruby-protocol-buffers)
+gem. This will use JSON as the data format and requires no extra gems besides
+the [json](http://flori.github.io/json/) gem, which is likely already installed
+on your machine.
+
+Betterific::JsonClient wraps the JSON response using
+[Hashie](https://github.com/intridea/hashie), so you may access the data using
+JSON object notation or via method calls. For example,
+
+    Betterific::JsonClient.betterifs(:id => [224])['total_results']
+
+is equivalent to
+
+    Betterific::JsonClient.betterifs(:id => [224]).total_results
+
+However, it is recommended that you use the latter notation since it is
+compatible with Betterific::ProtobufClient, whereas the JSON object notation is
+not.
+
+### Betterifs
+
+You can see the most popular betterifs of the last week using
+
+    Betterific::Client.betterifs(:most_popular)
+
+A similar call can be used to see the most recent betterifs
+
+    Betterific::Client.betterifs(:most_recent)
+
+If you already know the id(s) of the betterif(s) that you would like to see,
+you can use
+
+    Betterific::Client.betterifs(:ids => [id0, id1, ...])
+
+### Tags and Users
+
+You can see a list of tags or users by id using
+
+    Betterific::Client.tags(:ids => [id0, id1, ...])
+
+and
+
+    Betterific::Client.users(:ids => [id0, id1, ...])
+
+### Search
+
+You can search for betterifs, tags, users, or all of these using
+
+    Betterific::Client.search(:namespace => :all, :q => 'my query')
+
+Changing the _:namespace_ parameter will change the type of data returned.
+
+### Pagination
+
+All client methods take pagination params _:page_ and *:per_page*. In the case
+of most popular and most recent betterifs, the filter must be changed to a Hash
+parameter, like so
+
+    Betterific::Client.betterifs(:filter => :most_popular, :page => 2, :per_page => 10)
+
+and
+
+    Betterific::Client.betterifs(:filter => :most_recent, :page => 2, :per_page => 10)
+
+### Using Protocol Buffers
+
+If you have
+[ruby-protocol-buffers](https://github.com/codekitchen/ruby-protocol-buffers)
+installed, Betterific::Client will use Betterific::ProtobufClient in place of
+Betterific::JsonClient. This will greatly improve performance, as
+[Protocol Buffers](https://developers.google.com/protocol-buffers/) are highly
+optimized.
+
+The Betterific::ProtobufClient responds to the same methods as the
+Betterific::JsonClient, so it's easy to switch between implementations at will.
+For example,
+
+    Betterific::JsonClient.users(:id => [2])
+
+and
+
+    Betterific::ProtobufClient.users(:id => [2])
+
+return the same data as
+
+    Betterific::Client.users(:id => [2])
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,5 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new('spec')

data/betterific.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/betterific/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Brad Cater"]
+  gem.email         = ["bradcater@gmail.com"]
+  gem.description   = %q{This gem is a Ruby interface to the Betterific API.}
+  gem.summary       = %q{This gem is a Ruby interface to the Betterific API. It provides support via Protocol Buffers if the ruby-protocol-buffers gem is installed; otherwise, it uses JSON.}
+  gem.homepage      = "https://github.com/bradcater/betterific"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "betterific"
+  gem.require_paths = ["lib"]
+  gem.version       = Betterific::VERSION
+
+  gem.add_dependency 'hashie', '~> 2.0.5'
+  gem.add_dependency 'json', '~> 1.8.0'
+
+  gem.add_development_dependency 'ruby-protocol-buffers', '~> 2.4.0'
+  gem.add_development_dependency 'rspec', '~> 2.13.0'
+end

data/lib/betterific/client.rb

@@ -0,0 +1,24 @@
+module Betterific
+  module Client
+    # Delegate all methods to a client implementation if that client
+    # implementation supports the method. Use ProtobufClient if it's
+    # available; otherwise, use JsonClient.
+    #
+    CLIENT = if defined?(Betterific::ProtobufClient)
+      Betterific::ProtobufClient
+    else
+      Betterific::JsonClient
+    end
+    
+    def self.respond_to?(method) #:nodoc:
+      return true if CLIENT.respond_to?(method)
+      super
+    end
+    def self.method_missing(method, *args, &block) #:nodoc:
+      if CLIENT.respond_to?(method)
+        return CLIENT.send(method, *args, &block)
+      end
+      super
+    end
+  end
+end

data/lib/betterific/client_constants.rb

@@ -0,0 +1,22 @@
+module Betterific
+  module ClientConstants
+    # The base URL for the Betterific API.
+    BASE_URL = 'http://betterific.com/api'.freeze
+
+    # The base URL to GET betterifs.
+    BETTERIFS_BASE_URL = "#{BASE_URL}/betterifs".freeze
+    # The base URL to GET tags.
+    TAGS_BASE_URL = "#{BASE_URL}/tags".freeze
+    # The base URL to GET users.
+    USERS_BASE_URL = "#{BASE_URL}/users".freeze
+
+    # The base URL to GET search results.
+    SEARCH_BASE_URL = "#{BASE_URL}/search".freeze
+
+    # The package in which protocol buffer schemas are defined.
+    PROTO_PACKAGE_NAME = 'BetterIf'.freeze
+
+    # The directory in which to store temporary files.
+    TMP_DIR = File.expand_path(File.join('.', 'tmp'))
+  end
+end

data/lib/betterific/client_helpers.rb

@@ -0,0 +1,45 @@
+require 'net/http'
+
+module Betterific
+  module ClientHelpers
+    def get_http(uri, opts={}) #:nodoc:
+      res = Net::HTTP.get_response(uri)
+      unless res.is_a?(Net::HTTPSuccess)
+        raise "Could not connect to #{uri}"
+      end
+      res
+    end; private :get_http
+
+    def add_page_params(url, opts={}) #:nodoc:
+      to_add = []
+      if opts[:page]
+        unless valid_page_param?(opts[:page])
+          raise "Invalid page: #{opts[:page]}"
+        end
+        to_add << "page=#{opts[:page]}"
+      end
+      if opts[:per_page]
+        unless valid_page_param?(opts[:per_page])
+          raise "Invalid per_page: #{opts[:per_page]}"
+        end
+        to_add << "per_page=#{opts[:per_page]}"
+      end
+      if to_add.size > 0
+        url = "#{url}#{url =~ /\?/ ? '&' : '?'}#{to_add.join('&')}"
+      end
+      url
+    end; private :add_page_params
+
+    def page_params_from_opts(opts) #:nodoc:
+      return {} unless opts.is_a?(Hash)
+      [:page, :per_page].inject({}) do |hsh, k|
+        hsh[k] = opts[k]
+        hsh
+      end
+    end; private :page_params_from_opts
+
+    def valid_page_param?(p) #:nodoc:
+      p.is_a?(Fixnum) && p > 0 && p.to_i == p
+    end; private :valid_page_param?
+  end
+end

data/lib/betterific/json_client.rb

@@ -0,0 +1,89 @@
+require 'hashie'
+require 'json'
+
+module Betterific
+  module JsonClient
+    include ::Betterific::ClientConstants
+    class << self
+      include ::Betterific::ClientHelpers
+      def get_json(url, opts={}, url_params={}) #:nodoc:
+        url = add_page_params(url, page_params_from_opts(opts))
+        uri = URI(url)
+        unless url_params.empty?
+          uri.query = URI.encode_www_form(url_params)
+        end
+        Hashie::Mash.new(JSON.parse(get_http(uri).body))
+      end; private :get_json
+    end
+
+    # Get a list of betterifs.
+    #
+    # ==== Parameters
+    #
+    # * +opts+ - If most_popular, gets the most popular betterifs of the last
+    #   week.
+    #
+    #   If most_recent, gets the most recent betterifs.
+    #
+    #   {:ids => [id0, id1, ..., idx]} specifies the ids of the betterif(s) to
+    #   return.
+    def self.betterifs(opts={})
+      if [:most_popular, 'most_popular'].include?(opts) || (opts.is_a?(Hash) && [:most_popular, 'most_popular'].include?(opts[:filter]))
+        return get_json("#{BETTERIFS_BASE_URL}/most-popular")
+      elsif [:most_recent, 'most_recent'].include?(opts) || (opts.is_a?(Hash) && [:most_recent, 'most_recent'].include?(opts[:filter]))
+        return get_json("#{BETTERIFS_BASE_URL}/most-recent")
+      elsif opts[:ids]
+        return get_json("#{BETTERIFS_BASE_URL}?betterifs[ids]=#{Array(opts[:ids]).map(&:to_s).join(',')}")
+      else
+        raise "No filter and no ids given."
+      end
+    end
+
+    # Get a list of tags.
+    #
+    # ==== Parameters
+    #
+    # * +opts+ - {:ids => [id0, id1, ..., idx]} specifies the ids of the
+    #   tag(s) to return.
+    def self.tags(opts={})
+      if opts[:ids]
+        return get_json("#{TAGS_BASE_URL}?tags[ids]=#{Array(opts[:ids]).map(&:to_s).join(',')}")
+      else
+        raise "No ids given."
+      end
+    end
+
+    # Get a list of users.
+    #
+    # ==== Parameters
+    #
+    # * +opts+ - {:ids => [id0, id1, ..., idx]} specifies the ids of the
+    #   user(s) to return.
+    def self.users(opts={})
+      if opts[:ids]
+        return get_json("#{USERS_BASE_URL}?users[ids]=#{Array(opts[:ids]).map(&:to_s).join(',')}")
+      else
+        raise "No ids given."
+      end
+    end
+
+    # Search for betterifs, tags, and users.
+    #
+    # ==== Parameters
+    #
+    # * +opts+ - {:namespace => (all|betterifs|tags|users)} specifies the type
+    #   of object(s) to return.
+    #
+    #   {:q => <query>} specifies the search query.
+    def self.search(opts={})
+      raise "No namespace given." if opts[:namespace].nil?
+      raise "No q given." if opts[:q].nil?
+      raise "q is blank." if opts[:q].blank?
+      if [:betterifs, 'betterifs', :tags, 'tags', :users, 'users', :all, 'all'].include?(opts[:namespace])
+        return get_json("#{SEARCH_BASE_URL}/#{opts[:namespace]}?q=#{opts[:q]}")
+      else
+        raise "Invalid namespace: #{opts[:namespace]}"
+      end
+    end
+  end
+end

data/lib/betterific/protobuf_client.rb

@@ -0,0 +1,157 @@
+require 'protocol_buffers'
+require 'protocol_buffers/compiler'
+
+module Betterific
+  module ProtobufClient
+    include ::Betterific::ClientConstants
+    class << self
+      include ::Betterific::ClientHelpers
+      # Cache of the last time a schema was refreshed by name.
+      LAST_REFRESH = {}
+      # Cache of schemas by URI.
+      PROTO_SCHEMA_CACHE = {}
+      # How many seconds to keep a schema before refreshing.
+      PROTO_TTL_SECONDS = 60
+      def compile_and_load_string(kode, url) #:nodoc
+        unless Dir.exists?(self::TMP_DIR)
+          Dir.mkdir(self::TMP_DIR, 0700)
+        end
+        deps = fetch_and_save_dependencies(kode, url)
+        fname = url.split(/\//)[-1]
+        File.open(File.join(self::TMP_DIR, fname), 'w') do |f|
+          f.write(kode)
+        end
+        deps << fname
+        deps = deps.reject do |d|
+          Kernel.const_defined?(self::PROTO_PACKAGE_NAME.to_sym) && Kernel.const_get(self::PROTO_PACKAGE_NAME.to_sym)
+            .const_defined?(d.gsub(/\.proto$/, '').camelize.to_sym)
+        end
+        unless deps.empty?
+          ProtocolBuffers::Compiler.compile_and_load(deps.map do |d|
+            File.join(self::TMP_DIR, d)
+          end, :include_dirs => [self::TMP_DIR])
+        end
+      end; private :compile_and_load_string
+
+      def fetch_and_save_dependencies(kode, url) #:nodoc
+        kode.scan(/import\s+'([^']+)';/).map do |imp|
+          imp = imp.first
+          imp_url = [url.split(/\//)[0..-2], imp].flatten.join('/')
+          uri = URI(imp_url)
+          if LAST_REFRESH[uri].nil? || (LAST_REFRESH[uri] < Time.now - PROTO_TTL_SECONDS)
+            PROTO_SCHEMA_CACHE[uri] = get_http(URI(imp_url))
+            File.open(File.join(self::TMP_DIR, imp), 'w') do |f|
+              f.write(PROTO_SCHEMA_CACHE[uri].body)
+            end
+            LAST_REFRESH[uri] = Time.now
+          end
+          fetch_and_save_dependencies(PROTO_SCHEMA_CACHE[uri].body, url) + [imp]
+        end.flatten.uniq
+      end; private :fetch_and_save_dependencies
+      
+      def get_namespaced_class(klass_string, o=nil) #:nodoc
+        return o if klass_string == nil
+        unless klass_string.is_a?(Array)
+          klass_string = klass_string.split(/::/)
+        end
+        o ||= Kernel
+        o = o.const_get(klass_string.first)
+        return o if klass_string.size == 1
+        get_namespaced_class(klass_string[1..-1], o)
+      end; private :get_namespaced_class
+
+      def get_protobuf(url, opts={}, url_params={}) #:nodoc
+        url = add_page_params(url, page_params_from_opts(opts))
+        proto_url = if url =~ /\?/
+          url.gsub(/\?/, '.protobuf?')
+        else
+          "#{url}.protobuf"
+        end
+        uri = URI(proto_url)
+        unless url_params.empty?
+          uri.query = URI.encode_www_form(url_params)
+        end
+        res = get_http(uri)
+        schema_uri = URI(res.header['X-Protobuf-Schema'])
+        if PROTO_SCHEMA_CACHE[schema_uri].nil? || LAST_REFRESH[schema_uri] < Time.now - PROTO_TTL_SECONDS
+          PROTO_SCHEMA_CACHE[schema_uri] = get_http(schema_uri)
+          LAST_REFRESH[schema_uri] = Time.now
+        end
+        proto_name = schema_uri.to_s.split(/\//).last
+        compile_and_load_string(PROTO_SCHEMA_CACHE[schema_uri].body, schema_uri.to_s)
+        proto_klass = get_namespaced_class("#{self::PROTO_PACKAGE_NAME}::#{proto_name.gsub(/\.proto$/, '').camelize}")
+        proto_klass.parse(res.body)
+      end; private :get_protobuf
+    end
+
+    # Get a list of betterifs.
+    #
+    # ==== Parameters
+    #
+    # * +opts+ - If most_popular, gets the most popular betterifs of the last
+    #   week.
+    #
+    #   If most_recent, gets the most recent betterifs.
+    #
+    #   {:ids => [id0, id1, ..., idx]} specifies the ids of the betterif(s) to
+    #   return.
+    def self.betterifs(opts={})
+      if [:most_popular, 'most_popular'].include?(opts) || (opts.is_a?(Hash) && [:most_popular, 'most_popular'].include?(opts[:filter]))
+        return get_protobuf("#{BETTERIFS_BASE_URL}/most-popular")
+      elsif [:most_recent, 'most_recent'].include?(opts) || (opts.is_a?(Hash) && [:most_recent, 'most_recent'].include?(opts[:filter]))
+        return get_protobuf("#{BETTERIFS_BASE_URL}/most-recent")
+      elsif opts[:ids]
+        return get_protobuf("#{BETTERIFS_BASE_URL}?betterifs[ids]=#{Array(opts[:ids]).map(&:to_s).join(',')}")
+      else
+        raise "No filter and no ids given."
+      end
+    end
+
+    # Get a list of tags.
+    #
+    # ==== Parameters
+    #
+    # * +opts+ - {:ids => [id0, id1, ..., idx]} specifies the ids of the
+    #   tag(s) to return.
+    def self.tags(opts={})
+      if opts[:ids]
+        return get_protobuf("#{TAGS_BASE_URL}?tags[ids]=#{Array(opts[:ids]).map(&:to_s).join(',')}")
+      else
+        raise "No ids given."
+      end
+    end
+
+    # Get a list of users.
+    #
+    # ==== Parameters
+    #
+    # * +opts+ - {:ids => [id0, id1, ..., idx]} specifies the ids of the
+    #   user(s) to return.
+    def self.users(opts={})
+      if opts[:ids]
+        return get_protobuf("#{USERS_BASE_URL}?users[ids]=#{Array(opts[:ids]).map(&:to_s).join(',')}")
+      else
+        raise "No ids given."
+      end
+    end
+
+    # Search for betterifs, tags, and users.
+    #
+    # ==== Parameters
+    #
+    # * +opts+ - {:namespace => (all|betterifs|tags|users)} specifies the type
+    #   of object(s) to return.
+    #
+    #   {:q => <query>} specifies the search query.
+    def self.search(opts={})
+      raise "No namespace given." if opts[:namespace].nil?
+      raise "No q given." if opts[:q].nil?
+      raise "q is blank." if opts[:q].blank?
+      if [:betterifs, 'betterifs', :tags, 'tags', :users, 'users', :all, 'all'].include?(opts[:namespace])
+        return get_protobuf("#{SEARCH_BASE_URL}/#{opts[:namespace]}?q=#{opts[:q]}")
+      else
+        raise "Invalid namespace: #{opts[:namespace]}"
+      end
+    end
+  end
+end

data/lib/betterific/ruby_extensions.rb

@@ -0,0 +1,46 @@
+class Object
+  unless nil.respond_to?(:present?)
+    # Return true if self is not nil, false otherwise.
+    #
+    # This is defined only if it is not yet defined.
+    #
+    def present?
+      !self.nil?
+    end
+  end
+end
+
+class String
+
+  unless ''.respond_to?(:blank?)
+    # Return true if self has length 0 or is only whitespace, false otherwise.
+    #
+    # This is defined only if it is not yet defined.
+    #
+    def blank?
+      self.strip.size == 0
+    end
+  end
+
+  #Adapted from
+  #https://www.ruby-forum.com/topic/4411006
+  unless ''.respond_to?(:camelize)
+    # Return a camel-case version of self, in contrast to underscore.
+    #
+    # This is defined only if it is not yet defined.
+    #
+    def camelize
+      self.split('_').each(&:capitalize!).join
+    end
+  end
+  unless ''.respond_to?(:underscore)
+    # Return an underscore version of self, in contrast to camel-case.
+    #
+    # This is defined only if it is not yet defined.
+    #
+    def underscore
+      self.scan(/[A-Z][a-z]*/).join('_').downcase
+    end
+  end
+
+end

data/lib/betterific/version.rb

@@ -0,0 +1,3 @@
+module Betterific
+  VERSION = "0.0.1" #:nodoc:
+end

data/lib/betterific.rb

@@ -0,0 +1,21 @@
+require 'betterific/client_constants'
+require 'betterific/client_helpers'
+require 'betterific/ruby_extensions'
+require 'betterific/version'
+
+require 'betterific/json_client'
+if Gem::Specification.find_all_by_name('ruby-protocol-buffers').any?
+  require 'betterific/protobuf_client'
+else
+  puts 'Betterific: Install the ruby-protocol-buffers gem to use Betterific::ProtobufClient.'
+end
+
+require 'betterific/client'
+
+module Betterific
+  # See a human-readable form of this gem's current version.
+  #
+  def self.version_string
+    "Betterific version #{Betterific::VERSION}"
+  end
+end

data/spec/betterific_spec.rb

@@ -0,0 +1,7 @@
+require 'spec_helper'
+
+describe Betterific do
+  it 'should return correct version string' do
+    Betterific.version_string.should == "Betterific version #{Betterific::VERSION}"
+  end
+end

data/spec/client_spec.rb

@@ -0,0 +1,3 @@
+require 'spec_helper'
+
+client_test(Betterific::Client)

data/spec/json_client_spec.rb

@@ -0,0 +1,3 @@
+require 'spec_helper'
+
+client_test(Betterific::JsonClient)

data/spec/protobuf_client_spec.rb

@@ -0,0 +1,5 @@
+require 'spec_helper'
+
+if defined?(Betterific::ProtobufClient)
+  client_test(Betterific::ProtobufClient)
+end

data/spec/spec_helper.rb

@@ -0,0 +1,147 @@
+require 'betterific'
+
+BETTERIFIC_TAG_ID = 400937 #:nodoc
+BETTERIF_ID = 224 #:nodoc
+USER_ID = 2 #:nodoc
+
+SEARCH_KINDS = %w{betterifs tags users}.freeze #:nodoc
+
+def ensure_valid_api_response(resp, client_modjule, opts={})
+  if opts[:big]
+    resp.total_results.should > 10
+  else
+    resp.total_results.should >= (opts[:allow_empty] ? 0 : 1)
+  end
+  if opts[:big]
+    resp.num_results.should == 10
+  else
+    resp.num_results.should >= (opts[:allow_empty] ? 0 : 1)
+  end
+  if opts[:betterifs]
+    if opts[:big]
+      resp.betterifs.size.should == 10
+    else
+      resp.betterifs.size.should >= (opts[:allow_empty] ? 0 : 1)
+    end
+    unless opts[:allow_empty]
+      if client_modjule == Betterific::JsonClient
+        resp.betterifs.first.tags.is_a?(Array).should == true
+      elsif client_modjule == Betterific::ProtobufClient
+        resp.betterifs.first.tags.is_a?(ProtocolBuffers::RepeatedField).should == true
+      else
+        raise "Invalid client_modjule #{client_modjule}"
+      end
+      if resp.betterifs.first.tags.size > 0
+        if client_modjule == Betterific::ProtobufClient
+          resp.betterifs.first.tags.first.is_a?(BetterIf::Tag).should == true
+        end
+      end
+      if client_modjule == Betterific::ProtobufClient
+        resp.betterifs.first.user.is_a?(BetterIf::User).should == true
+      end
+    end
+  end
+  if opts[:tags]
+    if opts[:big]
+      resp.tags.size.should == 10
+    else
+      resp.tags.size.should >= (opts[:allow_empty] ? 0 : 1)
+    end
+    if client_modjule == Betterific::JsonClient
+      resp.tags.is_a?(Array).should == true
+    elsif client_modjule == Betterific::ProtobufClient
+      resp.tags.is_a?(ProtocolBuffers::RepeatedField).should == true
+    else
+      raise "Invalid client_modjule #{client_modjule}"
+    end
+    if client_modjule == Betterific::ProtobufClient && resp.tags.size > 0
+      resp.tags.first.is_a?(BetterIf::Tag).should == true
+    end
+  end
+  if opts[:users]
+    if opts[:big]
+      resp.users.size.should == 10
+    else
+      resp.users.size.should >= (opts[:allow_empty] ? 0 : 1)
+    end
+    if client_modjule == Betterific::JsonClient
+      resp.users.is_a?(Array).should == true
+    elsif client_modjule == Betterific::ProtobufClient
+      resp.users.is_a?(ProtocolBuffers::RepeatedField).should == true
+    else
+      raise "Invalid client_modjule #{client_modjule}"
+    end
+    if client_modjule == Betterific::ProtobufClient && resp.users.size > 0
+      resp.users.first.is_a?(BetterIf::User).should == true
+    end
+  end
+end
+
+def client_test(modjule)
+  describe modjule do
+    [['without page params', {}],
+     ['with page params', {:page => 2, :per_page => 1}]].each do |(page_params_lbl, page_params)|
+      describe page_params_lbl do
+        [:most_popular, :most_recent].each do |filter|
+          it "should load #{filter} betterifs" do
+            resp = modjule.betterifs(page_params.merge(:filter => filter))
+            ensure_valid_api_response(resp, :betterifs => true, :big => page_params.empty?)
+          end
+        end
+        it "should load betterifs via ids" do
+          resp = modjule.betterifs(page_params.merge(:ids => BETTERIF_ID))
+          ensure_valid_api_response(resp, :betterifs => true, :allow_empty => !page_params.empty?)
+          if page_params.empty?
+            resp.betterifs.first.id.should == BETTERIF_ID
+          end
+        end
+        it "should load tags via ids" do
+          resp = modjule.tags(page_params.merge(:ids => BETTERIFIC_TAG_ID))
+          ensure_valid_api_response(resp, :tags => true, :allow_empty => !page_params.empty?)
+          if page_params.empty?
+            resp.tags.first.id.should == BETTERIFIC_TAG_ID
+          end
+        end
+        it "should load users via ids" do
+          resp = modjule.users(page_params.merge(:ids => USER_ID))
+          ensure_valid_api_response(resp, :users => true, :allow_empty => !page_params.empty?)
+          if page_params.empty?
+            resp.users.first.id.should == USER_ID
+          end
+        end
+  
+        SEARCH_KINDS.each do |kind|
+          it "should load search for #{kind}" do
+            q = random_query
+            resp = modjule.search(page_params.merge(:namespace => kind, :q => q))
+            resp.q.should == q
+            ensure_valid_api_response(resp.send(kind), kind.to_sym => true, :allow_empty => true)
+            if modjule == Betterific::JsonClient
+              SEARCH_KINDS.each do |other_kind|
+                next if kind == other_kind
+                resp.send(other_kind).present?.should == false
+              end
+            end
+          end
+        end
+        it "should load search for all" do
+          q = random_query
+          resp = modjule.search(page_params.merge(:namespace => :all, :q => q))
+          resp.q.should == q
+          SEARCH_KINDS.each do |kind|
+            ensure_valid_api_response(resp.send(kind), kind.to_sym => true, :allow_empty => true)
+          end
+        end
+      end
+    end
+  end
+end
+
+def random_query
+  'abcdefghijklmnopqrstuvwxyz'.split(//).sample
+end
+
+RSpec.configure do |config|
+  config.color_enabled = true
+  config.formatter     = 'documentation'
+end

metadata

@@ -0,0 +1,135 @@
+--- !ruby/object:Gem::Specification
+name: betterific
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Brad Cater
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-07-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.0.5
+  prerelease: false
+  type: :runtime
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.0.5
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.8.0
+  prerelease: false
+  type: :runtime
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.8.0
+- !ruby/object:Gem::Dependency
+  name: ruby-protocol-buffers
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.13.0
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.13.0
+description: This gem is a Ruby interface to the Betterific API.
+email:
+- bradcater@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- betterific.gemspec
+- lib/betterific.rb
+- lib/betterific/client.rb
+- lib/betterific/client_constants.rb
+- lib/betterific/client_helpers.rb
+- lib/betterific/json_client.rb
+- lib/betterific/protobuf_client.rb
+- lib/betterific/ruby_extensions.rb
+- lib/betterific/version.rb
+- spec/betterific_spec.rb
+- spec/client_spec.rb
+- spec/json_client_spec.rb
+- spec/protobuf_client_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/bradcater/betterific
+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.25
+signing_key: 
+specification_version: 3
+summary: This gem is a Ruby interface to the Betterific API. It provides support via
+  Protocol Buffers if the ruby-protocol-buffers gem is installed; otherwise, it uses
+  JSON.
+test_files:
+- spec/betterific_spec.rb
+- spec/client_spec.rb
+- spec/json_client_spec.rb
+- spec/protobuf_client_spec.rb
+- spec/spec_helper.rb