token_master 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5790941a8c9d0ec6eacb36b1df7c473acc880c51
-  data.tar.gz: affb3fad61df083f6a9d723b638d55b3d8e8a27b
+  metadata.gz: dd04ff6bcd482acefe3cb6f02eef4cd186ef8722
+  data.tar.gz: 741a3a5d77632dd6736aaa7546d1aac10eafc69b
 SHA512:
-  metadata.gz: 4c88cfdaffea449b8393a25ee549972d4a746328f9b0adf7e25ffe9aaf87be9583d3f7ff0859eba2d7fb272050852f21ff298118456d9b1494eaf83b2b1455dc
-  data.tar.gz: d87767fbaf677e52b5aea2904564e5c7888133e288e747e2071d2c4b4248fc9102a85950a508ffe56b681600759d66a880b06230a7ce2b0e8c6c7d3173871afb
+  metadata.gz: 4f5937cb91561db88615e0dcb47e772fa0f9751ba70914cf2e7fcd7dc5e5b10a3226a95241c1fd666f9de0597ec860244c7d069914e09236d95260de28283ff2
+  data.tar.gz: 53ae9e0eb252be8acf703999eccba66fa40ac3d647137fa4e21db444b14e9b13fa3bad293dd89fdd76dd16e4c5b9fad1cc1a0173702658ef52a21813462fa5cb

data/.gitignore

@@ -1,3 +1,7 @@
 .DS_Store
-.yardoc
+token_master-*.gem
+Gemfile.lock
+coverage
+.yardopts
 doc
+.yardoc

data/.travis.yml

@@ -1 +1,8 @@
 language: ruby
+
+addons:
+  code_climate:
+    repo_token: 455155dab5ce38bdda48bd7f4a94dd1e460889794046165191e5cf0a680e1999
+
+after_success:
+  - bundle exec codeclimate-test-reporter

data/Gemfile

@@ -1,3 +1,8 @@
 source 'https://rubygems.org'
 
+group :test do
+  gem 'simplecov'
+  gem 'codeclimate-test-reporter', '~> 1.0.0'
+end
+
 gemspec

data/README.md

@@ -1,4 +1,10 @@
+[![GitHub](http://img.shields.io/badge/github-launchpadlab/token_master-blue.svg)](http://github.com/launchpadlab/token_master)
+[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://www.rubydoc.info/gems/token_master)
+
+[![Gem Version](https://badge.fury.io/rb/token_master.svg)](https://badge.fury.io/rb/token_master)
 [![Build Status](https://travis-ci.org/LaunchPadLab/token-master.svg?branch=master)](https://travis-ci.org/LaunchPadLab/token-master)
+[![Test Coverage](https://codeclimate.com/github/LaunchPadLab/token-master/badges/coverage.svg)](https://codeclimate.com/github/LaunchPadLab/token-master/coverage)
+[![License](http://img.shields.io/badge/license-MIT-yellowgreen.svg)](#license)
 
 # token-master
 User management logic using tokens
@@ -68,3 +74,6 @@ config.add_tokenable_options :confirm, TokenMaster::Config::DEFAULT_VALUES
 
 config.add_tokenable_options :reset, token_lifetime: 1, required_params: [:password, :password_confirmation], token_length: 15
 ```
+
+## Api Documentation
+[Rdoc](http://www.rubydoc.info/gems/token_master)

data/Rakefile

@@ -1,13 +1,8 @@
 require 'rake/testtask'
-require 'yard'
 
 Rake::TestTask.new do |t|
   t.libs << 'test'
 end
 
-YARD::Rake::YardocTask.new do |t|
-  t.files = ['lib/**/*.rb']
-end
-
 desc 'Run tests'
 task default: :test

data/lib/token_master.rb

@@ -14,4 +14,4 @@ require 'token_master/core'
 require 'token_master/error'
 require 'token_master/model'
 require 'token_master/version'
-require 'token_master/railtie' if defined?(::Rails)
+require 'token_master/railtie' if defined?(::Rails)

data/lib/token_master/config.rb

@@ -1,5 +1,11 @@
 module TokenMaster
+  # `TokenMaster::Config` manages the configuration options for tokenable actions. These can be set with the initializer provided with the generator. Default values will be used if options are not specified
   class Config
+
+    # Provides default values for a tokenable action:
+    # * `token_lifetime` is an integer representing the number of days before the token expires
+    # * `required_params` is an array of symbols, e.g., `[:password, :password_confirmation]`
+    # * `token_length` is an integer representing the number of characters in the token
     DEFAULT_VALUES = {
       token_lifetime: 14,
       required_params: [],
@@ -8,26 +14,50 @@ module TokenMaster
 
     attr_accessor :options
 
+    # Creates a new instance of `TokenMaster::Config`
     def initialize
       @options = {}
     end
 
+    # Sets the key-value pairs needed to complete a tokenable action<br /> Key-value pairs used to complete a tokenable action are the `token_lifetime`, `required_params` (can be blank), and `token_length`
+    # @example Set a Tokenable Option
+    #   config.add_tokenable_options(:invite, { token_lifetime: 10, required_params: [:password, :password_confirmation], token_length: 12 }) #=>
+    #   { invite: {
+    #       token_lifetime: 10,
+    #       required_params: [:password, :password_confirmation],
+    #       token_length: 12
+    #      }
+    #    }
+    # @param [Symbol] key the tokenable action
+    # @param [Symbol=>[Integer, String, Array]] params the key-value pairs
     def add_tokenable_options(key, **params)
       @options[key] = params
     end
 
+    # Retrieves the `required_params` for a tokenable_action, either as set by the application, or by the default<br /> Used to update model attributes as needed for a given tokenable action
+    # @param [Symbol] key the tokenable action
+    # @return [Array] the `required_params` for a tokenable action
     def get_required_params(key)
       get_option(key, :required_params)
     end
 
+    # Retrieves the `token_lifetime` for a tokenable action, either as set by the application, or by the default
+    # @param [Symbol] key the tokenable action
+    # @return [Integer] the `token_lifetime` for a tokenable action
     def get_token_lifetime(key)
       get_option(key, :token_lifetime)
     end
 
+    # Retrieves the `token_length` for a tokenable action, either as set by the application, or by the default
+    # @param [Symbol] key the tokenable action
+    # @return [Integer] the `token_length` for a tokenable action
     def get_token_length(key)
       get_option(key, :token_length)
     end
 
+    # Determines whether options are provided for a tokenable action
+    # @param [Symbol] key the tokenable action
+    # @return [Boolean] `true` => options are set; `false` => options are not set
     def options_set?(key)
       @options.key? key
     end

data/lib/token_master/core.rb

@@ -2,10 +2,21 @@ require 'token_master/error'
 require 'securerandom'
 
 module TokenMaster
-  # TODO
+  # `TokenMaster::Core` provides the core functionality of the TokenMaster gem. The `Core` module performs all of the logic of completing tokenable actions, and provides descriptive messages of the status or abilities of calls made.
   module Core
     class << self
-      # TODO
+
+      # Completes the tokenable action for a tokenable model instance using a token, setting `tokenable_completed_at` to the time at completion
+      # @param [Object] klass the tokenable Class
+      # @param [String, Symbol] key the tokenable action
+      # @param token [String] the tokenable's token used to complete the action
+      # @param params [Symbol=>String] keyword arguments required to complete the tokenable action
+      # @raise [NotTokenableError] if the provided Class does not have the correct tokenable column
+      # @raise [TokenNotFoundError] if a tokenable instance cannot be found by the given token
+      # @raise [TokenCompletedError] if the tokenable action has already been completed, i.e., the tokenable instance has a timestamp in `tokenable_completed_at`
+      # @raise [TokenExpiredError] if the token is expired, i.e., the date is beyond the token's `created_at` plus `token_lifetime`
+      # @raise [MissingRequiredParamsError] if the params required by a tokenable are not provided
+      # @return [Object] tokenable Class instance
       def do_by_token!(klass, key, token, **params)
         check_manageable! klass, key
         token_column = { token_col(key) => token }
@@ -19,7 +30,16 @@ module TokenMaster
         model
       end
 
-      # TODO
+      # Completes the token action for a tokenable instance _without_ a token, setting the `tokenable_completed_at` to the time at completion.<br /> Usually implemented when you want to complete multiple tokenable actions at once, e.g., a user completes the invite action by setting up passwords, by default also completes the confirm action
+      # @example Force a Tokenable Action (Confirm)
+      #   user.force_confirm! =>
+      #     <User id: 205, name: "John Smith", email: "jsmith@example.com", confirm_token: nil, confirm_created_at: nil, confirm_sent_at: nil, confirm_completed_at: "2017-04-25 14:17:13">
+      # @param [Object] model the tokenable model instance
+      # @param [String, Symbol] key the tokenable action
+      # @param [Symbol=>String] params keyword arguments required to complete the tokenable action
+      # @raise [NotTokenableError] if the provided Class does not have the correct tokenable column
+      # @raise [MissingRequiredParamsError] if the params required by a tokenable are not provided
+      # @return [Object] tokenable Class instance
       def force_tokenable!(model, key, **params)
         check_manageable! model.class, key
         check_params! key, params
@@ -30,10 +50,14 @@ module TokenMaster
         model
       end
 
-      # TODO
+      # Generates a tokenable action token, sets the token and the time of creation on the tokenable model instance
+      # @param [Object] model the tokenable model instance
+      # @param [String, Symbol] key the tokenable action
+      # @param [Integer] token_length the length of the generated token, method will use configuration token_length if not provided otherwise
+      # @raise [NotTokenableError] if the provided Class does not have the correct tokenable column
+      # @return [String] token
       def set_token!(model, key, token_length = nil)
         check_manageable! model.class, key
-        check_configs_set! key
         token_length ||= TokenMaster.config.get_token_length(key.to_sym)
         token = generate_token token_length
 
@@ -47,7 +71,16 @@ module TokenMaster
         token
       end
 
-      # TODO
+      # Accepts a block to pass on a generated token through a block, such as a mailer method, and sets `tokenable_sent_at` to the time the method is called
+      # @example Send Reset Instructions
+      #   user.send_reset_instruction! { user.send_email } =>
+      #     <User id: 205, name: "John Smith", email: "jsmith@example.com", reset_token: "3YcHkTJ7kXwV5wM", reset_created_at: 2017-04-25 14:20:54", reset_sent_at: "2017-04-25 14:22:42", reset_completed_at: nil>
+      # @param [Object] model the tokenable model instance
+      # @param [String, Symbol] key  the tokenable action
+      # @raise [NotTokenableError] if the provided Class does not have the correct tokenable column
+      # @raise [TokenNotSetError] if the tokenable model instance does not have a token for the tokenable action
+      # @raise [TokenSentError] if this has already been called for the instance and tokenable action, i.e., `tokenable_sent_at` is not `nil`
+      # @return [Object] tokenable model instance
       def send_instructions!(model, key)
         check_manageable! model.class, key
         check_token_set! model, key
@@ -59,7 +92,16 @@ module TokenMaster
         model.save(validate: false)
       end
 
-      # TODO
+      # Provides the status of the tokenable action, whether the action has been completed, the token has been sent, the token is expired, or the token has only been created
+      # @param [Object] model the tokenable model instance
+      # @param [String, Symbol] key  the tokenable action
+      # @raise [NotTokenableError] if the provided Class does not have the correct tokenable column
+      # @return [String] status of the tokenable action:
+      #  * completed
+      #  * sent
+      #  * expired
+      #  * created
+      #  * no token
       def status(model, key)
         check_manageable! model.class, key
         return 'completed' if completed?(model, key)
@@ -93,12 +135,8 @@ module TokenMaster
           TokenMaster.config.get_token_lifetime(key.to_sym)
         end
 
-        def required_params(key)
-          TokenMaster.config.required_params(key.to_sym)
-        end
-
         def check_manageable!(klass, key)
-          raise NotTokenable, "#{klass} not #{key}able" unless manageable?(klass, key)
+          raise Errors::NotTokenable, "#{klass} not #{key}able" unless manageable?(klass, key)
         end
 
         def manageable?(klass, key)
@@ -112,21 +150,17 @@ module TokenMaster
           ).all? { |attr| column_names.include? attr }
         end
 
-        def check_configs_set!(key)
-          raise NotConfigured, 'You have not set the configurations for this tokenable.' unless TokenMaster.config.options_set?(key.to_sym)
-        end
-
         def check_params!(key, params)
           required_params = TokenMaster.config.get_required_params(key.to_sym)
-          raise MissingRequiredParams, 'You did not pass in the required params for this tokenable' unless required_params.all? do |k|
+          raise Errors::MissingRequiredParams, 'You did not pass in the required params for this tokenable' unless required_params.all? do |k|
             params.keys.include? k
           end
         end
 
         def check_token_active!(model, key)
-          raise TokenNotFound, "#{key} token not found" unless model
-          raise TokenCompleted, "#{key} already completed" if completed?(model, key)
-          raise TokenExpired, "#{key} token expired" unless token_active?(model, key)
+          raise Errors::TokenNotFound, "#{key} token not found" unless model
+          raise Errors::TokenCompleted, "#{key} already completed" if completed?(model, key)
+          raise Errors::TokenExpired, "#{key} token expired" unless token_active?(model, key)
         end
 
         def token_active?(model, key)
@@ -136,7 +170,7 @@ module TokenMaster
         end
 
         def check_instructions_sent!(model, key)
-          raise TokenSent, "#{key} already sent" if instructions_sent?(model, key)
+          raise Errors::TokenSent, "#{key} already sent" if instructions_sent?(model, key)
         end
 
         def instructions_sent?(model, key)
@@ -148,17 +182,13 @@ module TokenMaster
         end
 
         def check_token_set!(model, key)
-          raise TokenNotSet, "#{key}_token not set" unless token_set?(model, key)
+          raise Errors::TokenNotSet, "#{key}_token not set" unless token_set?(model, key)
         end
 
         def completed?(model, key)
           model.send(completed_at_col(key)).present?
         end
 
-        def check_completed!(model, key)
-          raise TokenNotCompleted, "#{key} not completed" unless completed?(model, key)
-        end
-
         def generate_token(length)
           rlength = (length * 3) / 4
           SecureRandom.urlsafe_base64(rlength).tr('lIO0', 'sxyz')

data/lib/token_master/error.rb

@@ -1,36 +1,32 @@
 module TokenMaster
+  # `TokenMaster::Errors` holds all of the error classes used in applying TokenMaster
+  module Errors
+    # The base class for all errors raised by TokenMaster
+    class Error < StandardError; end
 
-  # The base class for all errors raised by TokenMaster
-  class Error < StandardError; end
+    # Raised when the attributes for a tokenable do not exist.
+    # This could result from a migration not being run or a spelling error
+    class NotTokenable < Error; end
 
-  # TODO
-  class MissingRequiredParams < Error; end
+    # Raised when the required parameters for a tokenable are not provided.
+    # This typically happens with reset and invite tokenables, that might require both `password` and `password_confirmation` fields,
+    # but only one is provided to the method
+    class MissingRequiredParams < Error; end
 
-  # Raised when the attributes for a tokenable do not exist.
-  # This could result from a migration not being run or a spelling error
-  class NotTokenable < Error; end
+    # Raised when the tokenable instance is not found
+    class TokenNotFound < Error; end
 
-  # TODO
-  class NotConfigured < Error; end
+    # Raised when the status of the token is reviewed, but the tokenable action has already been completed
+    class TokenCompleted < Error; end
 
-  # TODO
-  class MissingRequiredParams < Error; end
+    # Raised when the token has expired based on the tokenable's `token_lifetime`
+    class TokenExpired < Error; end
 
-  # TODO
-  class TokenNotFound < Error; end
+    # Raised when the tokenable instructions have already been sent when calling `send_tokenable_instructions!`
+    class TokenSent < Error; end
 
-  # TODO
-  class TokenCompleted < Error; end
-
-  # TODO
-  class TokenNotCompleted < Error; end
-
-  # TODO
-  class TokenExpired < Error; end
-
-  # TODO
-  class TokenSent < Error; end
-
-  # TODO
-  class TokenNotSet < Error; end
+    # Raised when the tokenable model instance does not have a token set for a tokenable action
+    class TokenNotSet < Error; end
+  end
 end
+

data/lib/token_master/model.rb

@@ -1,34 +1,41 @@
 module TokenMaster
 
-  # TODO
+  # `TokenMaster::Model` provides the interface to the app it is used in, providing access to its public methods by invoking `TokenMaster::ClassMethods` and definiing the appropriate methods on the app model(s).
   module Model
+    # Includes `TokenMaster::Model` and extends `TokenMaster::ClassMethods` to the class it's used with (automatically included via Railties)
     def self.included(base)
       base.extend(ClassMethods)
     end
 
+    # `TokenMaster::ClassMethods` defines methods on the tokenable Class to be used in applying TokenMaster
     module ClassMethods
-      # TODO
+      # Iterates over each of the tokenables provided in the generator arguments to define the appropriate TokenMaster methods on the tokenable model
       def token_master(*tokenables)
         tokenables.each do |tokenable|
           # instance methods
-          # TODO
+
+          # Defines a method on the tokenable model instance to generate a tokenable action token, e.g., `user.set_confim_token!`
           define_method("set_#{tokenable}_token!") do
             TokenMaster::Core.set_token!(self, tokenable)
           end
-          # TODO
-          define_method("send_#{tokenable}_instructions!") do |email|
-            TokenMaster::Core.send_instructions!(self, tokenable, email)
+
+          # Defines a method on the tokenable model instance to send tokenable action instructions, e.g., `user.send_confim_instructions!`. Accepts a block with app logic to send instructions.
+          define_method("send_#{tokenable}_instructions!") do |&email|
+            TokenMaster::Core.send_instructions!(self, tokenable, &email)
           end
-          # TODO
+
+          # Defines a method on the tokenable model instance to retrieve the status of a tokenable action, e.g., `user.confim_status`
           define_method("#{tokenable}_status") do
             TokenMaster::Core.status(self, tokenable)
           end
-          # TODO
+
+          # Defines a method on the tokenable model instance to force the completion of a tokenable action, e.g., `user.force_confim!`. Accepts keyword arguments for `required_params`.
           define_method("force_#{tokenable}!") do |**params|
             TokenMaster::Core.force_tokenable!(self, tokenable, **params)
           end
           # class methods
-          # TODO
+
+          # Defines a method on the tokenable model class to completed a tokenable action given a token, e.g., `User.confim_by_token!`. Takes the token and accepts any keyword arguments for `required_params`.
           define_singleton_method("#{tokenable}_by_token!") do |token, **params|
             TokenMaster::Core.do_by_token!(self, tokenable, token, **params)
           end

data/lib/token_master/version.rb

@@ -1,3 +1,4 @@
 module TokenMaster
-  VERSION = '0.0.1'.freeze
+  # Current version of TokenMaster
+  VERSION = '0.1.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: token_master
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Dave Corwin
@@ -61,7 +61,6 @@ files:
 - ".ruby-version"
 - ".travis.yml"
 - Gemfile
-- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -98,7 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.6
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Token Master!

data/Gemfile.lock

@@ -1,23 +0,0 @@
-PATH
-  remote: .
-  specs:
-    token_master (0.0.1)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    minitest (5.10.1)
-    rake (10.4.2)
-    yard (0.9.8)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  minitest (~> 5.10.1)
-  rake (~> 10.4.2)
-  token_master!
-  yard
-
-BUNDLED WITH
-   1.14.5