wanikani 1.5.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 138c753cc3cd8de0fdc6431696fafef58e6cc0b2
-  data.tar.gz: cd01ab65169dc4e9ef4a0e82b82efa0b15d86908
+  metadata.gz: d8206559d936c9724dbff8cc1c351d5e20864fae
+  data.tar.gz: 7ea4d78d466a1ec67e1990d89689a6a25a3e2b6c
 SHA512:
-  metadata.gz: f5722801a57c16801ba3104fac258d7bd4a4a5a97aa340a5c8787d89a7d27df03b702212744b1b656eb85ea90299cee9fe93d7bbcf860d905aac407d4694fb8a
-  data.tar.gz: 44e0dd55615a5ee0f9243ad3ea7f94db1308725f250535f87ec61e6b32fd4c7e8232f89ad0aa6e538f94754358f87aeb8f8592bdd2d6286cf2e6b6de8fdf14ea
+  metadata.gz: b4290df649685629cdf96047fd9563eedaad293e11b0bbd411d176d56a13db789edfa737bb40100e20d4fd572481ed884c12df164faab4502da705d09f05e8cd
+  data.tar.gz: f24cab27971276e4ad939e4b6d1af4e16283fa46ff98b661bc44bbdd7acb99b8d853d488c24cb7982c9ac5270fa53bb545cef5d7966c93a8517837ff2d1cbeef

data/lib/wanikani.rb

@@ -1,14 +1,5 @@
 # -*- encoding : utf-8 -*-
-require 'faraday'
-require 'faraday_middleware'
-
-require 'wanikani/user'
-require 'wanikani/study_queue'
-require 'wanikani/level'
-require 'wanikani/srs'
-require 'wanikani/recent_unlocks'
-require 'wanikani/critical_items'
-require 'wanikani/exceptions'
+require 'wanikani/client'
 
 Encoding.default_external = Encoding::UTF_8
 Encoding.default_internal = Encoding::UTF_8
@@ -18,67 +9,6 @@ module Wanikani
   DEFAULT_API_VERSION = "v1.4"
   VALID_API_VERSIONS = %w(v1 v1.1 v1.2 v1.3 v1.4)
 
-  def self.api_key=(api_key)
-    @api_key = api_key
-  end
-
-  def self.api_key
-    @api_key
-  end
-
-  def self.api_version=(api_version)
-    raise ArgumentError, "API version should be one of the following: #{VALID_API_VERSIONS.join(', ')}." unless VALID_API_VERSIONS.include?(api_version) || api_version.nil?
-    @api_version = api_version
-  end
-
-  def self.api_version
-    @api_version ||= DEFAULT_API_VERSION
-  end
-
-  def self.api_response(resource, optional_arg = nil)
-    raise ArgumentError, "You must define a resource to query Wanikani" if resource.nil? || resource.empty?
-    raise ArgumentError, "You must set your Wanikani API key before querying the API" if Wanikani.api_key.nil? || Wanikani.api_key.empty?
-
-    begin
-      res = client.get("/api/#{Wanikani.api_version}/user/#{Wanikani.api_key}/#{resource}/#{optional_arg}")
-
-      if !res.success? || res.body.has_key?("error")
-        self.raise_exception(res)
-      else
-        return res.body
-      end
-    rescue => error
-      raise Exception, "There was an error: #{error.message}"
-    end
-  end
-
-  def self.valid_api_key?(api_key = nil)
-    api_key ||= Wanikani.api_key
-    return false if api_key.nil? || api_key.empty?
-
-    res = client.get("/api/#{Wanikani.api_version}/user/#{api_key}/user-information")
-
-    return false if !res.success? || res.body.has_key?("error")
-    return true
-  end
-
-  private
-
-  def self.client
-    Faraday.new(url: Wanikani::API_ENDPOINT) do |conn|
-      conn.response :json, :content_type => /\bjson$/
-      conn.adapter Faraday.default_adapter
-    end
-  end
-
-  def self.raise_exception(response)
-    raise Wanikani::InvalidKey, "The API key used for this request is invalid." and return if response.status == 401
-
-    message = if response.body.is_a?(Hash) and response.body.has_key?("error")
-                response.body["error"]["message"]
-              else
-                "Status code: #{response.status}"
-              end
-    raise Wanikani::Exception, "There was an error fetching the data from Wanikani (#{message})"
-  end
+  class InvalidKey < Exception; end
+  class Exception < Exception; end
 end

data/lib/wanikani/client.rb

@@ -0,0 +1,109 @@
+# -*- encoding : utf-8 -*-
+require 'faraday'
+require 'faraday_middleware'
+
+require 'wanikani/user'
+require 'wanikani/study_queue'
+require 'wanikani/level'
+require 'wanikani/srs'
+require 'wanikani/recent_unlocks'
+require 'wanikani/critical_items'
+
+module Wanikani
+  class Client
+    include Wanikani::User
+    include Wanikani::StudyQueue
+    include Wanikani::Level
+    include Wanikani::SRS
+    include Wanikani::RecentUnlocks
+    include Wanikani::CriticalItems
+
+    attr_accessor :api_key, :api_version
+
+    # Initialize a client which will be used to communicate with WaniKani.
+    #
+    # @param options [Hash] the API key (required) and API version (optional)
+    #   used to communicate with the WaniKani API.
+    # @return [Wanikani::Client] an instance of Wanikani::Client.
+    def initialize(options = {})
+      raise ArgumentError, "You must specify a WaniKani API key before querying the API." if options[:api_key].nil? || options[:api_key].empty?
+      raise ArgumentError, "API version should be one of the following: #{Wanikani::VALID_API_VERSIONS.join(', ')}." unless Wanikani::VALID_API_VERSIONS.include?(options[:api_version]) || options[:api_version].nil?
+
+      @api_key = options[:api_key]
+      @api_version = options[:api_version] ||= Wanikani::DEFAULT_API_VERSION
+    end
+
+    # Verifies if the client's API key is valid by checking WaniKani's API.
+    #
+    # @param api_key [String] the API key to validate in WaniKani.
+    # @return [Boolean] whether the API key is valid.
+    def valid_api_key?(api_key = nil)
+      api_key ||= @api_key
+      return false if api_key.empty?
+
+      res = client.get("/api/#{@api_version}/user/#{api_key}/user-information")
+
+      return false if !res.success? || res.body.has_key?("error")
+      return true
+    end
+
+    # Verifies if the specified API key is valid by checking WaniKani's API.
+    #
+    # @param api_key [String] the API key to validate in WaniKani.
+    # @return [Boolean] whether the API key is valid.
+    def self.valid_api_key?(api_key = nil)
+      raise ArgumentError, "You must specify a WaniKani API key before querying the API." if api_key.nil? || api_key.empty?
+
+      @client = Wanikani::Client.new(api_key: api_key)
+      return @client.valid_api_key?
+    end
+
+    private
+
+    # Sets up the HTTP client for communicating with the WaniKani API.
+    #
+    # @return [Faraday::Connection] the HTTP client to communicate with the
+    #   WaniKani API.
+    def client
+      Faraday.new(url: Wanikani::API_ENDPOINT) do |conn|
+        conn.response :json, :content_type => /\bjson$/
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    # Contacts the WaniKani API and returns the data specified.
+    #
+    # @param resource [String] the resource to access.
+    # @param optional_arg [String] optional arguments for the specified resource.
+    # @return [Hash] the parsed API response.
+    def api_response(resource, optional_arg = nil)
+      raise ArgumentError, "You must define a resource to query WaniKani" if resource.nil? || resource.empty?
+
+      begin
+        res = client.get("/api/#{@api_version}/user/#{@api_key}/#{resource}/#{optional_arg}")
+
+        if !res.success? || res.body.has_key?("error")
+          raise_exception(res)
+        else
+          return res.body
+        end
+      rescue => error
+        raise Exception, "There was an error: #{error.message}"
+      end
+    end
+
+    # Handles exceptions according to the API response.
+    #
+    # @param response [Hash] the parsed API response from WaniKani's API.
+    def raise_exception(response)
+      raise Wanikani::InvalidKey, "The API key used for this request is invalid." and return if response.status == 401
+
+      message = if response.body.is_a?(Hash) and response.body.has_key?("error")
+                  response.body["error"]["message"]
+                else
+                  "Status code: #{response.status}"
+                end
+      raise Wanikani::Exception, "There was an error fetching the data from WaniKani (#{message})"
+    end
+  end
+end

data/lib/wanikani/critical_items.rb

@@ -1,23 +1,23 @@
 # -*- encoding : utf-8 -*-
 module Wanikani
-  class CriticalItems
+  module CriticalItems
     # Gets the user's current items under 'Critical Items'.
     #
-    # @param [Integer] percentage maximum percentage
-    # @return [Array] Returns hashes of critical items and their related information.
-    def self.critical(percentage = 75)
+    # @param percentage [Integer] the maximum percentage of correctness.
+    # @return [Array<Hash>] critical items and their related information.
+    def critical_items(percentage = 75)
       raise ArgumentError, "Percentage must be an Integer between 0 and 100" if !percentage.between?(0, 100)
-      api_response = Wanikani.api_response("critical-items", percentage)
-      return api_response["requested_information"]
+      response = api_response("critical-items", percentage)
+      return response["requested_information"]
     end
 
     # Gets the full response of the Critical Items List API call.
     #
-    # @param [Integer] percentage maximum percentage
-    # @return [Hash] Full response from the Critical Items List API call.
-    def self.full_response(percentage = 75)
+    # @param percentage [Integer] the maximum percentage of correctness.
+    # @return [Hash] full response from the Critical Items List API call.
+    def full_critical_items_response(percentage = 75)
       raise ArgumentError, "Percentage must be an Integer between 0 and 100" if !percentage.between?(0, 100)
-      return Wanikani.api_response("critical-items", percentage)
+      return api_response("critical-items", percentage)
     end
   end
 end

data/lib/wanikani/level.rb

@@ -1,37 +1,67 @@
 # -*- encoding : utf-8 -*-
 module Wanikani
-  class Level
+  module Level
     # Gets the user's current level progression (radicals and Kanji).
     #
-    # @return [Hash] Progress and total of radicals and Kanji for the user's current level.
-    def self.progression
-      api_response = Wanikani.api_response("level-progression")
-      current_level = { "current_level" => api_response["user_information"]["level"] }
-      return api_response["requested_information"].merge(current_level)
+    # @return [Hash] progress and total of radicals and Kanji for the user's current level.
+    def level_progression
+      response = api_response("level-progression")
+      current_level = { "current_level" => response["user_information"]["level"] }
+      return response["requested_information"].merge(current_level)
+    end
+
+    # Gets the user's full list of radicals and stats.
+    #
+    # @param levels [Integer, Array<Integer>] a specific level or array of
+    #   levels to fetch items for.
+    # @return [Hash] radicals with the user's stats.
+    def radicals_list(levels = nil)
+      return level_items_list("radicals", levels)
+    end
+
+    # Gets the user's full list of kanji and stats.
+    #
+    # @param levels [Integer, Array<Integer>] a specific level or array of
+    #   levels to fetch items for.
+    # @return [Hash] kanji with the user's stats.
+    def kanji_list(levels = nil)
+      return level_items_list("kanji", levels)
+    end
+
+    # Gets the user's full list of vocabulary and stats.
+    #
+    # @param levels [Integer, Array<Integer>] a specific level or array of
+    #   levels to fetch items for.
+    # @return [Hash] vocabulary with the user's stats.
+    def vocabulary_list(levels = nil)
+      return level_items_list("vocabulary", levels)
     end
 
     # Gets the full response of the Level Progression API call.
     #
-    # @return [Hash] Full response from the Level Progression API call.
-    def self.full_response
-      return Wanikani.api_response("level-progression")
+    # @return [Hash] full response from the Level Progression API call.
+    def full_level_progression_response
+      return api_response("level-progression")
     end
 
     private
 
-    def self.method_missing(name, *args)
-      super unless [:radicals, :kanji, :vocabulary].include?(name)
-
-      levels = args.push
+    # Fetches the specified item type list from WaniKani's API
+    #
+    # @param type [String] The type of item to fetch.
+    # @param levels [Integer, Array<Integer>] a specific level or array of
+    #   levels to fetch items for.
+    # @return [Hash] list of items of the specified type and levels.
+    def level_items_list(type, levels)
       levels = levels.join(',') if levels.is_a?(Array)
-      api_response = Wanikani.api_response(name.to_s, levels)
+      response = api_response(type, levels)
 
       # The vocabulary API call without specifying levels returns a Hash instead
       # of an Array, so this is a hacky way of dealing with it.
-      if api_response["requested_information"].is_a?(Hash)
-        return api_response["requested_information"]["general"]
+      if response["requested_information"].is_a?(Hash)
+        return response["requested_information"]["general"]
       else
-        return api_response["requested_information"]
+        return response["requested_information"]
       end
     end
   end

data/lib/wanikani/recent_unlocks.rb

@@ -1,32 +1,25 @@
 # -*- encoding : utf-8 -*-
 module Wanikani
-  class RecentUnlocks
+  module RecentUnlocks
     # Gets the recent unlocked items (radicals, Kanji and vocabulary).
     #
-    # @param [Integer] limit the total number of items returned.
-    # @return [Array] Returns hashes of unlocked items and related information.
-    def self.list(limit = 10)
-      api_response = Wanikani.api_response("recent-unlocks", limit)
-      return api_response["requested_information"]
+    # @param options [Hash] the options to limit the number and type of items.
+    # @return [Array<Hash>] hashes of unlocked items and related information.
+    def recent_unlocks(options = {})
+      response = api_response("recent-unlocks", options[:limit])
+      if options[:type]
+        return response["requested_information"].select { |unlock| unlock["type"] == options[:type] }
+      else
+        return response["requested_information"]
+      end
     end
 
     # Gets the full response of the Recents Unlocks List API call.
     #
-    # @param [Integer] limit the total number of items returned.
-    # @return [Hash] Full response from the Recent Unlocks List API call.
-    def self.full_response(limit = 10)
-      return Wanikani.api_response("recent-unlocks", limit)
-    end
-
-    private
-
-    def self.method_missing(name, *args)
-      super unless [:radicals, :vocabulary, :kanji].include?(name)
-
-      limit = args.shift || 10
-      type = name == :radicals ? name.to_s.chop! : name.to_s
-      unlock_list = self.list(limit)
-      return unlock_list.select { |unlock| unlock["type"] == type }
+    # @param options [Integer] limit the total number of items returned.
+    # @return [Hash] full response from the Recent Unlocks List API call.
+    def full_recent_unlocks_response(options = {})
+      return api_response("recent-unlocks", options[:limit])
     end
   end
 end

data/lib/wanikani/srs.rb

@@ -1,17 +1,17 @@
 # -*- encoding : utf-8 -*-
 module Wanikani
-  class SRS
+  module SRS
     ITEM_TYPES = %w(apprentice guru master enlighten burned all)
 
     # Gets the counts for each SRS level and item types.
     #
-    # @param [String] item_type the SRS level that will be returned.
-    # @return [Hash] Returns the SRS information for each level for the user.
-    def self.distribution(item_type = "all")
+    # @param item_type [String] the SRS level that will be returned.
+    # @return [Hash] the SRS information for each level for the user.
+    def srs_distribution(item_type = "all")
       raise ArgumentError, "Please use a valid SRS type (or none for all types)" if !ITEM_TYPES.include?(item_type)
 
-      api_response = Wanikani.api_response("srs-distribution")
-      srs_distribution = api_response["requested_information"]
+      response = api_response("srs-distribution")
+      srs_distribution = response["requested_information"]
 
       return srs_distribution if item_type == "all"
       return srs_distribution[item_type]
@@ -19,14 +19,14 @@ module Wanikani
 
     # Gets all items for a specific SRS level.
     #
-    # @param [String] item_type the SRS level for the items returned.
-    # @return [Array] Returns all the items matching the specified SRS for each level for the user.
-    def self.items_by_type(item_type)
+    # @param item_type [String] the SRS level for the items returned.
+    # @return [Array<Hash>] all the items matching the specified SRS for each level for the user.
+    def srs_items_by_type(item_type)
       raise ArgumentError, "Please use a valid SRS type." if !ITEM_TYPES.include?(item_type) || item_type == "all"
 
       items_by_type = []
       %w(radicals kanji vocabulary).each do |type|
-        items = Wanikani::Level.send(type)
+        items = send("#{type}_list")
         items.reject! { |item| item["user_specific"].nil? || item["user_specific"]["srs"] != item_type }.map! do |item|
           item.merge!("type" => (type == 'radicals' ? 'radical' : type))
         end
@@ -38,9 +38,9 @@ module Wanikani
 
     # Gets the full response of the SRS Distribution API call.
     #
-    # @return [Hash] Full response from the SRS Distribution API call.
-    def self.full_response
-      return Wanikani.api_response("srs-distribution")
+    # @return [Hash] full response from the SRS Distribution API call.
+    def full_srs_distribution_response
+      return api_response("srs-distribution")
     end
   end
 end

data/lib/wanikani/study_queue.rb

@@ -1,33 +1,33 @@
 # -*- encoding : utf-8 -*-
 module Wanikani
-  class StudyQueue
+  module StudyQueue
     # Get the number of lessons and reviews that are currently in the user's queue.
     #
-    # @return [Hash] Returns the number of lessons and reviews pending, along with upcoming review information.
-    def self.queue
-      api_response = Wanikani.api_response("study-queue")
-      return api_response["requested_information"]
+    # @return [Hash] the number of lessons and reviews pending, along with upcoming review information.
+    def study_queue
+      response = api_response("study-queue")
+      return response["requested_information"]
     end
 
     # Check if there are lessons available.
     #
-    # @return [Boolean] Returns true if there's at least one lesson available, or false if there are none.
-    def self.lessons_available?
-      return !self.queue["lessons_available"].zero?
+    # @return [Boolean] true if there's at least one lesson available, or false if there are none.
+    def lessons_available?
+      return !study_queue["lessons_available"].zero?
     end
 
     # Check if there are reviews available.
     #
-    # @return [Boolean] Returns true if there's at least one review available, or false if there are none.
-    def self.reviews_available?
-      return !self.queue["reviews_available"].zero?
+    # @return [Boolean] true if there's at least one review available, or false if there are none.
+    def reviews_available?
+      return !study_queue["reviews_available"].zero?
     end
 
     # Gets the full response of the Study Queue API call.
     #
-    # @return [Hash] Full response from the Study Queue API call.
-    def self.full_response
-      return Wanikani.api_response("study-queue")
+    # @return [Hash] full response from the Study Queue API call.
+    def full_study_queue_response
+      return api_response("study-queue")
     end
   end
 end

data/lib/wanikani/user.rb

@@ -1,33 +1,33 @@
 # -*- encoding : utf-8 -*-
 module Wanikani
-  class User
+  module User
     # Gets the user information from WaniKani.
     #
-    # @return [Hash] The user information for the WaniKani account by from the API key.
-    def self.information
-      api_response = Wanikani.api_response("user-information")
-      return api_response["user_information"]
+    # @return [Hash] the user information for the WaniKani account by from the API key.
+    def user_information
+      response = api_response("user-information")
+      return response["user_information"]
     end
 
     # Checks if the user is currently in vacation mode.
     #
     # @return [Boolean] true if vacation_date contains a timestamp, false if
     #   vacation_date is null.
-    def self.on_vacation?
-      api_response = Wanikani.api_response("user-information")
-      vacation_date = api_response["user_information"]["vacation_date"]
+    def on_vacation?
+      response = api_response("user-information")
+      vacation_date = response["user_information"]["vacation_date"]
       return !vacation_date.nil?
     end
 
     # Returns the Gravatar image URL using the Gravatar hash from the user's information.
     #
-    # @param options [Hash] Optional settings for the gravatar URL.
-    # @return [String] The Gravatar URL, with the optional size parameter, nil if
+    # @param options [Hash] optional settings for the gravatar URL.
+    # @return [String, nil] the Gravatar URL, with the optional size parameter, nil if
     #   the user information contains no Gravatar hash.
-    def self.gravatar_url(options = {})
+    def gravatar_url(options = {})
       raise ArgumentError, "The size parameter must be an integer" if options[:size] && !options[:size].is_a?(Integer)
-      api_response = Wanikani.api_response("user-information")
-      hash = api_response["user_information"]["gravatar"]
+      response = api_response("user-information")
+      hash = response["user_information"]["gravatar"]
 
       return nil if hash.nil?
       return build_gravatar_url(hash, options)
@@ -35,14 +35,19 @@ module Wanikani
 
     # Gets the full response of the User Information API call.
     #
-    # @return [Hash] Full response from the User Information API call.
-    def self.full_response
-      return Wanikani.api_response("user-information")
+    # @return [Hash] full response from the User Information API call.
+    def full_user_response
+      return api_response("user-information")
     end
 
     private
 
-    def self.build_gravatar_url(hash, options)
+    # Builds the URL for displaying the Gravatar URL with different params.
+    #
+    # @param hash [String] the Gravatar hash for the user's image.
+    # @param options [Hash] optional params for building the Gravatar URL.
+    # @return [String] the Gravatar URL according to the specified params.
+    def build_gravatar_url(hash, options = {})
       params = "d=mm" # Use 'Mystery Man' image if no image found.
       params += "&size=#{options[:size]}" if options[:size]
 

data/lib/wanikani/version.rb

@@ -1,3 +1,3 @@
 module Wanikani
-  VERSION = '1.5.0'
+  VERSION = '2.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wanikani
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Dennis Martinez
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-25 00:00:00.000000000 Z
+date: 2017-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -73,8 +73,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/wanikani.rb
+- lib/wanikani/client.rb
 - lib/wanikani/critical_items.rb
-- lib/wanikani/exceptions.rb
 - lib/wanikani/level.rb
 - lib/wanikani/recent_unlocks.rb
 - lib/wanikani/srs.rb
@@ -85,7 +85,9 @@ homepage: https://github.com/dennmart/wanikani-gem
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message: |2
+      Version 2.0 of the wanikani gem introduces many breaking changes.
+      Please view the README for more information: https://github.com/dennmart/wanikani-gem
 rdoc_options: []
 require_paths:
 - lib
@@ -101,7 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: Add Japanese Kanji learning goodness to your Ruby projects!

data/lib/wanikani/exceptions.rb

@@ -1,4 +0,0 @@
-module Wanikani
-  class InvalidKey < Exception; end
-  class Exception < Exception; end
-end