lexile 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3b3572b7bf5426c44e0887f4c77425129a96fd3d
+  data.tar.gz: e7e3897e33a3c90d8d83bd63e3c5b04b7d11430a
+SHA512:
+  metadata.gz: 9d503217391a94ffe678eb940d0037557c32a5f9faf194f018c3f1065009ea61ffb266422f5bafa612894106ec24d968db3798852f3b23ef10b345d3cb7eacf3
+  data.tar.gz: b0aea8b1285bf7c94cca0fc3431e32d6e36bc2bac1be29489c9bab0ac833db4aa810550d30c239f6111a1a635553f033fa6d4ea8a3554ea28ae8c96d571b00f5

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.idea/

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+cache: bundler
+
+rvm:
+  - 2.1.2
+
+script: 'CODECLIMATE_REPO_TOKEN=cd173d6c860a8493b813ea4ed982824b180b0c50604e3a27c3a3c83e94868d71 bundle exec rake'
+
+notifications:
+  email:
+    recipients:
+      - mauricio@curriculet.com
+    on_failure: change
+    on_success: never

data/Gemfile

@@ -0,0 +1,17 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in lexile.gemspec
+gemspec
+
+gem 'httparty',   '~> 0.10'
+gem 'hashie',     '~> 2.0'
+
+group :development, :test do
+  gem 'rspec', '~> 2'
+  gem 'webmock'
+  gem 'vcr',   '~> 2.8'
+  gem 'jeweler'
+  gem 'factory_girl'
+end
+
+gem "codeclimate-test-reporter", group: :test, require: nil

data/LICENSE.txt

@@ -0,0 +1,22 @@
+
+The MIT License (MIT)
+
+Copyright (c) 2014 Curriculet Inc
+
+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,93 @@
+[![Build Status](https://travis-ci.org/curriculet/lexile.svg?branch=master)](https://travis-ci.org/Curriculet/Lexile) 
+[![Code Climate](https://codeclimate.com/github/curriculet/lexile/badges/gpa.svg)](https://codeclimate.com/github/curriculet/lexile)
+[![Test Coverage](https://codeclimate.com/github/curriculet/lexile/badges/coverage.svg)](https://codeclimate.com/github/curriculet/lexile)  
+[![GitHub version](https://badge.fury.io/gh/curriculet%2Flexile.svg)](http://badge.fury.io/gh/curriculet%2Flexile)
+
+# Lexile® 
+
+This gem wraps a portion of the Lexile database API. You need to obtain an
+authorized username and password from Lexile to use the API. This gem is not
+meant to be a comprenhensive implementation of the API just a bare bones
+"Find the Lexile for a Specific Book" solution.
+
+The gem only covers the endpoints to the `book` resource, the `category` and
+`serial` resources are beyond the scope of this gem . If you need access
+ to these resources feel free to submit a PR with code and specs.
+
+The gem does not support pagination for result-sets longer than 20 books, while
+the API contains all provisions for pagination, it is beyond the scope of the
+gem to expose those.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'lexile'
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install lexile
+
+## Usage
+
+    >>  b = Lexile.books.show("315833")
+    #<Lexile::Book id= "315833" ISBN="006201272X" ISBN13="9780062012722" ... >
+
+    >>  b.title
+    "It Happened to Nancy: By An Anonymous Teenager: A True Story from Her Diary"
+
+
+
+    >> b = Lexile.books.find_by_isbn13("9780062012722")
+    [#<Lexile::Book ISBN="006201272X" ISBN13="9780062012722" ... >]
+
+    >>  b[0].title
+    "It Happened to Nancy: By An Anonymous Teenager: A True Story from Her Diary"
+
+
+
+    >>  b = Lexile.books.find_by_title("to Nancy")
+    [#<Lexile::Book ISBN="0380773155" ISBN13="9780380773152" ... >, #<Lexile::Book ISBN="006201272X" ISBN13="9780062012722" ... >]
+
+    >> b.length
+    2
+
+    >>  b[0].title
+    "It Happened to Nancy: By An Anonymous Teenager: A True Story from Her Diary"
+
+
+## Contributing
+
+1. Fork it ( http://github.com/<my-github-username>/lexile/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes and specs(`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+The MIT License (MIT)
+
+Copyright (c) 2014 Curriculet Inc
+
+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/Rakefile

@@ -0,0 +1,30 @@
+require "rubygems/package_task"
+require "bundler/gem_tasks"
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+gem_spec = eval(File.read("./lexile.gemspec")) rescue nil
+Gem::PackageTask.new(gem_spec) do |pkg|
+  pkg.need_zip = false
+  pkg.need_tar = false
+end
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/lexile.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'lexile/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "lexile"
+  spec.version       = Lexile::VERSION
+
+  spec.authors       = ["Mauricio Alvarez"]
+  spec.email         = ["mauricio@curriculet.com"]
+  spec.date          = "2014-10-25"
+  spec.description   = "A gem for the Lexile® database API "
+  spec.summary       = "A gem to find a book's Lexile DB entry by name or ISBN13"
+  spec.homepage      = "https://github.com/curriculet/lexile"
+  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.10"
+  spec.add_runtime_dependency "hashie", "~> 2.0.0"
+end

data/lib/lexile/api/books.rb

@@ -0,0 +1,26 @@
+module Lexile
+  module Api
+    class Books < Resource
+      api_model Lexile::Book
+
+      def show id
+        response = @client.get( "#{ api_model.api_path }/#{id}" )
+        api_model.parse(response.body)
+      end
+
+      def find( query_params )
+        response = @client.get( "#{ api_model.api_path }", query_params )
+        api_model.parse(response.body)
+      end
+
+      def find_by_isbn13 isbn13
+        self.find( {"ISBN13" => isbn13 })
+      end
+
+      def find_by_title title
+        self.find( {"title__contains" => title } )
+      end
+
+    end
+  end
+end

data/lib/lexile/api/client.rb

@@ -0,0 +1,105 @@
+module Lexile
+  module API
+    class Client
+      include HTTParty
+
+      # initialize
+      #
+      # The Lexile Api Client can be configured via Lexile.configure block
+      # or via a hash with the appropriate values set
+      #
+      # endpoint:     required. The API endpoing i.e https://api.lexile.com
+      # api_version:  required. The API version (v1 or V1.1)
+      # username:     required. Your lexile username
+      # password:     required. Your lexile password
+      # timeout:      optional. The HTTP timeout
+      # testing:      optional. Set it to true to activate debugging output
+      #
+      # @param configuration [Lexile Hash] A hash or Lexile::Configuration that contains the parameters to
+      #     be used when issuing HTTP Calls
+      def initialize( configuration )
+
+        if configuration.is_a?(Module) && configuration.to_s == 'Lexile'
+          config = configuration
+        elsif configuration.is_a?(Hash)
+          config = Hashie::Mash.new( configuration )
+          config.api_url = [config.endpoint,config.api_version].join('/')
+        end
+
+        #if config.api_key
+          #self.class.default_params({ 'api_key' => config.api_key})
+        #else
+          #raise Lexile::InvalidCredentials.new("Api Key is not present but it is required.")
+        #end
+
+        self.class.base_uri( config.api_url )                     if config.api_url
+        self.class.default_timeout config.timeout.to_f            if config.timeout
+        self.class.debug_output                                   if config.testing
+        self.class.headers({'User-Agent' => config.user_agent})   if config.user_agent
+      end
+
+      # get
+      # send an HTTPS Get request against Edelement's API.
+      # Yields the get_options before sending making the request.
+      #
+      #
+      # @param path    [String] The path for the api endpoint (with leading slash)
+      # @param params  [Hash]   A hash of query arguments for the request (optional)
+      # @param headers [Hash]   A hash of header fields (optional).
+      #
+      #
+      # @return [String]. The raw response body (JSON is expected) Raises appropriate exception if it fails
+      # @raise Lexile::HTTPError when any HTTP error response is received
+      def get( path, params={}, headers={})
+        get_options = build_get_options( params, headers)
+        yield get_options if block_given?
+
+        #puts "CALLING API: #{Lexile.api_url}#{path} ===#{get_options}"
+        response = self.class.get( path, get_options)
+
+        case response.code
+        when 200..201
+          response
+        when 400
+          raise Lexile::BadRequest.new(response, params)
+        when 401
+          raise Lexile::AuthenticationFailed.new(response, params)
+        when 404
+          raise Lexile::NotFound.new(response, params)
+        when 500
+          raise Lexile::ServerError.new(response, params)
+        when 502
+          raise Lexile::Unavailable.new(response, params)
+        when 503, 504
+          raise Lexile::RateLimited.new(response, params)
+        else
+          raise Lexile::UnknownStatusCode.new(response, params)
+        end
+      end
+
+      # build_get_options
+      # Build the hash of options for an HTTP get request.
+      #
+      # @param params  [Hash] optional. Any query parameters to add to the request.
+      # @param user_headers [Hash] optional. Any query parameters to add to the request.
+      #
+      # @return [Hash] The properly formated get_options.
+      def build_get_options( params={}, user_headers={})
+        get_options = {}
+        query ={ format: 'json'} #all requests get this query params
+
+        query.merge!(params)
+
+        # pass any headers
+        headers ={}
+        headers.merge!( user_headers )
+
+        get_options[:query]      = query
+        get_options[:headers]    = headers
+        get_options[:basic_auth] = { username: Lexile.options[:username],
+                                     password: Lexile.options[:password]}
+        get_options
+      end
+    end
+  end
+end

data/lib/lexile/api/endpoints.rb

@@ -0,0 +1,20 @@
+module Lexile
+  module Api
+    module Endpoints
+
+
+      # books
+      #
+      # @example
+      #   Lexile.books.find(title: or isbn:  ) returns the details of book
+      #
+      # @return [Lexile::Api::Books] A properly initialized books api client ready for calls
+
+
+      def books
+        @books ||= Lexile::Api::Books.new( client )
+      end
+
+    end
+  end
+end

data/lib/lexile/api/resource.rb

@@ -0,0 +1,27 @@
+module Lexile
+  module Api
+    class Resource
+      class << self
+        #api_model
+        #
+        # It tells the parser which Lexile::Model to use when parsing JSON and creating objects
+        #
+        # @param klass [Lexile::Model] The Lexile::Model class to be used when parsing and objectifying responses.
+        def api_model(klass)
+          class_eval <<-END
+                  def api_model
+          #{klass}
+                  end
+          END
+        end
+      end
+
+      # initialize
+      # @param client [Lexile::API::Client] required to issue HTTP calls
+      def initialize( client )
+        @client = client
+      end
+
+    end
+  end
+end

data/lib/lexile/book.rb

@@ -0,0 +1,41 @@
+module Lexile
+  class Book < Hashie::Mash
+    include Lexile::Model
+
+    api_path '/book'
+
+    # Book Resource
+    #
+    # This is the resource you will likely be using most often.  This represents a book.
+    #
+    # Field                	Type     	Filter	Description
+    # ISBN                 	string   	ALL	    International Standard Book Number
+    # booktype		          string   	ALL	    Booktype, e.g. Fiction
+    # lexile_code		        string   	n/a	    Lexile Code, e.g. GN (graphic novel)
+    # series			          string   	ALL	    Book Series, if any
+    # lexile_code_spanish	  string		n/a	    Lexile Code for Spanish Lexile measure if available
+    # word_count		        integer		ALL	    Number of words contained in the book
+    # keyword		            string		ALL	    List of keywords
+    # serial			          integer		gt      Serial Number this Resource was last modified on
+    # id			              integer		n/a	    ID
+    # max_age	 	            integer		ALL	    Max age of book
+    # call_number		        string		n/a	    Call Number
+    # copyright		          string		n/a	    Copyright year
+    # author			          string		ALL	    Book Author(s)
+    # lexile			          integer		ALL	    Lexile Measure
+    # categories_display	  string		n/a	    List of categories
+    # timestamp		          datetime 	gt,gte	Date/time the book record was last modified
+    # min_age		            integer		ALL	    Minimum age of book
+    # pages			            integer		ALL	    Number of pages contained in the book
+    # categories		        related		ALL	    List of URIs or individually nested resource data
+    # publisher		          string		ALL	    Book publisher
+    # language		          string		ALL	    Book's written language
+    # ISBN13			          string		ALL	    13-digit ISBN
+    # lexile_spanish		    integer		n/a	    Spanish Lexile Measure
+    # word_count_spanish   	integer		n/a	    Number of words in Spanish version of book
+    # summary		            string		n/a	    Summary of the book
+    # title			            string		ALL	    Book Title
+    # resource_uri		      string		n/a	    The resource url for accessing this resource directly
+    #
+  end
+end

data/lib/lexile/configuration.rb

@@ -0,0 +1,73 @@
+module Lexile
+  module Configuration
+    VALID_CONNECTION_KEYS = [:endpoint, :api_version, :user_agent, :testing, :timeout].freeze
+    VALID_OPTIONS_KEYS    = [:username,:password].freeze
+
+    #@!visibility private
+    VALID_CONFIG_KEYS     = VALID_CONNECTION_KEYS + VALID_OPTIONS_KEYS
+
+    DEFAULT_ENDPOINT      = 'https://fabapi.lexile.com/api/fab'
+    DEFAULT_API_VERSION   = 'v2'
+    DEFAULT_USER_AGENT    = 'Lexile API Ruby Gem by Curriculet'.freeze
+    DEFAULT_TIMEOUT       = nil
+    DEFAULT_TESTING       = false
+    DEFAULT_USERNAME      = nil
+    DEFAULT_PASSWORD      = nil
+
+    # Build accessor methods for every config options so we can do this, for example:
+    attr_accessor *VALID_CONFIG_KEYS
+
+    # Make sure we have the default values set when we get 'extended'
+    def self.extended(base)
+      base.reset!
+    end
+
+    # reset!
+    # set all options to their defaults and free the client
+    def reset!
+      self.endpoint     = DEFAULT_ENDPOINT
+      self.api_version  = DEFAULT_API_VERSION
+      self.user_agent   = DEFAULT_USER_AGENT
+      self.timeout      = DEFAULT_TIMEOUT
+      self.testing      = DEFAULT_TESTING
+      self.username     = DEFAULT_USERNAME
+      self.password     = DEFAULT_PASSWORD
+
+      @client           = nil
+    end
+
+    #@return [Hash] of all options
+    def options
+      Hash[ * VALID_CONFIG_KEYS.map { |key| [key, send(key)] }.flatten ]
+    end
+
+    # api_url
+    # Interpolate the base url for all calls
+    # return [String] the base url for all api calls
+    def api_url( path = nil)
+      [endpoint,api_version,path].compact.join('/')
+    end
+
+    # Yields itself for use in the configuration block
+    # @example
+    #  Lexile.configure do |c|
+    #    c.api_key    = <MY-API-KEY>
+    #    c.api_verion = 'v2'
+    #    c.endpoint   = 'https://fabapi.lexile.com/api/fab/'
+    #    c.timeout    = '10' #seconds
+    #    c.testing    = true
+    #  end
+    #
+    # @return Lexile::API::Client
+    #
+    def configure
+      yield self
+      @client = Lexile::API::Client.new( self )
+    end
+
+    protected
+    def client
+      @client ||= Lexile::API::Client.new( self )
+    end
+  end # Configuration
+end

data/lib/lexile/errors.rb

@@ -0,0 +1,27 @@
+module Lexile
+  class InvalidCredentials < StandardError; end
+  class CannotProcessResponse < StandardError; end
+
+  class HTTPError < StandardError
+    attr_reader :response
+    attr_reader :params
+
+    def initialize(response, params = {})
+      @response = response
+      @params = params
+      super(response)
+    end
+
+    def to_s
+      "#{self.class.to_s} : #{response.code} #{response.body}"
+    end
+  end
+
+  class NotFound              < HTTPError; end
+  class Unavailable           < HTTPError; end
+  class BadRequest            < HTTPError; end
+  class ServerError           < HTTPError; end
+  class AuthenticationFailed  < HTTPError; end
+  class RateLimited           < HTTPError; end
+  class UnknownStatusCode     < HTTPError; end
+end

data/lib/lexile/model.rb

@@ -0,0 +1,103 @@
+module Lexile
+  module Model
+    def self.included(base)
+      base.send :extend, ClassMethods
+    end
+
+    module ClassMethods
+      # api_path
+      # This sets the API path so the API collections can use them in an agnostic way
+      # @param path [String] the api path for the current model with a leading slash
+      # @return [void]
+      def api_path(path = nil)
+        @_api_path ||= path
+      end
+
+      # Understanding the Response
+      # The API will return a JSON response for each query.  Lets take a look at a sample response.
+      #
+      #       {"meta":
+      #                 {"limit": 20, "next": null, "offset": 0, "previous": null, "total_count": 1},
+      #       "objects":
+      #           [
+      #               {
+      #                   "ISBN": "1234567890",
+      #                   "ISBN13": "9781234567890",
+      #                   "author": "Author, Fake",
+      #                   "booktype": "Fiction",
+      #                   "call_number": "",
+      #                   "categories":
+      #                       [{"id": 1, "name": "Action", "resource_uri": "/api/fab/2013-02-04/category/1/"}],
+      #                   "categories_display": "",
+      #                   "copyright": "2013",
+      #                   "id": 1,
+      #                   "keyword": "",
+      #                   "language": "",
+      #                   "lexile": 1000,
+      #                   "lexile_code": "",
+      #                   "lexile_code_spanish": "",
+      #                   "lexile_display": "1000L",
+      #                   "lexile_spanish": null,
+      #                   "max_age": null,
+      #                   "min_age": null,
+      #                   "pages": 5,
+      #                   "publisher":
+      #                   "Fake Publisher",
+      #                   "resource_uri": "/api/fab/2013-02-04/book/1/",
+      #                   "serial": 1,
+      #                   "series": "",
+      #                   "summary": "This is a sample summary",
+      #                   "timestamp": "2013-05-04T17:43:50",
+      #                   "title": "Test Book",
+      #                   "word_count": 400,
+      #                   "word_count_spanish": null
+      #               }
+      #           ]
+      #       }
+      #
+      # We will mainly cover the meta data in the response in this section.  For more details about the book object
+      # itself please refer to the resources documentation. Lets take a look at just the meta block.
+      #
+      #      {"meta":{"limit": 20, "next": null, "offset": 0, "previous": null, "total_count": 1}
+      #
+      # In the meta object you will find key pieces of information about your result.
+      # limit: By default only 20 objects are sent back in each response.  You can increase or decrease this limit by
+      # supplying a limit filter on your query.
+      #
+      # next:  The url for you to fetch the next set of results in your query.  This url will not be a fully qualified
+      # url but instead relative to the base url we discussed earlier.  If the value is none there is not another set
+      # of results and you have reached the last "page"
+      #
+      # offset: The number of records you are offsetting this result by.  For example if you had a limit of 20 and
+      # there were 100 total records.  If you had an offset of 60 that would mean you are looking at records 61-80.
+      #
+      # previous: Same as next but refers to the previous set of results. If this is null there are no previous sets
+      # available.
+      #
+      # total_count:  The total number of results in the query.  For example if you had a query that generated 100
+      # results this number would be 100.
+      #
+      # A field that is not explained in the resources documentation that should be noted here is resource_uri.
+      # You will notice in our sample response there is a resource_uri for the category and the book.  This is the
+      # url you will use to obtain information about that particular object.  Like the next and previous urls, this is
+      # not fully qualified and is relative to the base url discussed earlier.
+
+      # Parses a request.body response into a Lexile::Model objects
+      #
+      def parse( raw_json )
+        parsed_json = String === raw_json ? JSON.parse(raw_json) : json
+        if parsed_json.has_key?('objects')
+          #this is a multi record and data should contain an array
+          unless parsed_json['objects'].is_a? Array
+            raise Lexile::CannotProcessResponse.new('[:objects] is present in response but it does not contain an Array')
+          end
+          return parsed_json['objects'].map {|array_element|  new( array_element )  }
+        else
+          return  new( parsed_json )
+        end
+      end
+
+    end
+
+  end
+end

data/lib/lexile/version.rb

@@ -0,0 +1,3 @@
+module Lexile
+  VERSION = "0.0.2"
+end