Merge pull request #7 from ignaciojonas/v2

V2

.gitignore

@@ -1,5 +1,6 @@
 bin/
 vendor/
+doc/
 .DS_Store
 .ruby-version
 coverage

.travis.yml

@@ -9,3 +9,5 @@ rvm:
   - 2.2.1
 
 script: ./build_travis.sh
+
+after_success: ./deploy_documentation.sh

Gemfile

@@ -7,4 +7,5 @@ group :development do
   gem 'terminal-notifier-guard', require: false
   gem 'coveralls', require: false
   gem 'rubocop', require: false
+  gem 'yard', require: false
 end

README.md

@@ -19,35 +19,33 @@ gem 'auth0'
 
 ## Basic usage
 
-Using [APIv1](https://auth0.com/docs/api)
+Using [APIv2](https://auth0.com/docs/api/v2)
 
 ```ruby
 require "auth0"
 
 auth0 = Auth0Client.new(
-  :client_id => "YOUR CLIENT ID",
-  :client_secret => "YOUR CLIENT SECRET",
+  :token => "YOUR JWT HERE",
   :domain => "<YOUR ACCOUNT>.auth0.com"
 )
 
 puts auth0.get_users
 ```
 
-Using [APIv2](https://auth0.com/docs/apiv2)
+Using [APIv1](https://auth0.com/docs/api/v1)
 
 ```ruby
 require "auth0"
 
 auth0 = Auth0Client.new(
-  :api_version => 2,
-  :token => "YOUR JWT HERE",
+  :client_id => "YOUR CLIENT ID",
+  :client_secret => "YOUR CLIENT SECRET",
   :domain => "<YOUR ACCOUNT>.auth0.com"
 )
 
 puts auth0.get_users
 ```
 
-
 ## What is Auth0?
 
 Auth0 helps you to:

Rakefile

@@ -3,10 +3,33 @@ require 'bundler/gem_tasks'
 
 begin
   require 'rubocop/rake_task'
-  RuboCop::RakeTask.new
 
   require 'rspec/core/rake_task'
 
+  desc 'Run Rubocop'
+  RuboCop::RakeTask.new(:rubocop)
+
+  require 'yard'
+  DOC_FILES = ['lib/auth0/api/v2/*.rb']
+
+  desc 'Build Documentation'
+  YARD::Rake::YardocTask.new(:documentation) do |t|
+    t.files = DOC_FILES
+  end
+
+  desc 'Publish SDK documentation'
+  task :publish do
+    sh 'rake documentation'
+    sh 'cp -R doc /tmp/ruby-auth0-doc'
+    sh 'git checkout gh-pages'
+    sh 'cp -R /tmp/ruby-auth0-doc/* .'
+    sh 'rm -rf /tmp/ruby-auth0-doc'
+    sh 'git add .'
+    sh 'git commit -am "Rebuild documentation"'
+    sh 'git push origin gh-pages'
+    sh 'git checkout master'
+  end
+
   desc 'Run Integration Tests'
   RSpec::Core::RakeTask.new(:integration) do |t|
     t.pattern = FileList["spec/integration/**/*#{ENV['PATTERN']}*_spec.rb"]

auth0.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
   s.require_paths = ['lib']
 
-  s.add_runtime_dependency 'httparty', '~> 0.13'
+  s.add_runtime_dependency 'httmultiparty', '~> 0.3.16'
 
   s.add_development_dependency 'rake', '~> 10.4'
   s.add_development_dependency 'fuubar', '~> 2.0'

deploy_documentation.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# exit with nonzero exit code if anything fails
+set -e
+
+# clear and re-create the out directory
+rm -rf doc || exit 0;
+mkdir doc;
+
+# build documentation
+bundle exec rake documentation
+
+# go to the out directory and create a *new* Git repo
+cd doc
+git init
+
+# inside this git repo we'll pretend to be a new user
+git config user.name "Travis CI"
+git config user.email "[email protected]"
+
+# The first and only commit to this new Git repo contains all the
+# files present with the commit message "Deploy to GitHub Pages".
+git add .
+git commit -m "Deploy to GitHub Pages"
+
+# Force push from the current repo's master branch to the remote
+# repo's gh-pages branch. (All previous history on the gh-pages branch
+# will be lost, since we are overwriting it.) We redirect any output to
+# /dev/null to hide any sensitive credential data that might otherwise be exposed.
+git push --force --quiet "https://${GH_TOKEN}@${GH_REF}" master:gh-pages > /dev/null 2>&1

lib/auth0/api/v2.rb

@@ -1,20 +1,28 @@
-require 'auth0/api/v2/clients'
-require 'auth0/api/v2/users'
 require 'auth0/api/v2/blacklists'
+require 'auth0/api/v2/clients'
+require 'auth0/api/v2/connections'
+require 'auth0/api/v2/emails'
 require 'auth0/api/v2/jobs'
+require 'auth0/api/v2/rules'
 require 'auth0/api/v2/stats'
-require 'auth0/api/v2/connections'
+require 'auth0/api/v2/users'
+require 'auth0/api/v2/tenants'
+require 'auth0/api/v2/tickets'
 
 module Auth0
   module Api
     # https://auth0.com/docs/apiv2
     module V2
-      include Auth0::Api::V2::Clients
-      include Auth0::Api::V2::Users
       include Auth0::Api::V2::Blacklists
+      include Auth0::Api::V2::Clients
+      include Auth0::Api::V2::Connections
+      include Auth0::Api::V2::Emails
       include Auth0::Api::V2::Jobs
+      include Auth0::Api::V2::Rules
       include Auth0::Api::V2::Stats
-      include Auth0::Api::V2::Connections
+      include Auth0::Api::V2::Users
+      include Auth0::Api::V2::Tenants
+      include Auth0::Api::V2::Tickets
     end
   end
 end

lib/auth0/api/v2/blacklists.rb

@@ -1,22 +1,43 @@
 module Auth0
   module Api
     module V2
-      # https://auth0.com/docs/apiv2#!/blacklists
+      # Methods to use the blacklist endpoints
       module Blacklists
-        # https://auth0.com/docs/apiv2#!/blacklists/get_tokens
-        def blacklisted_tokens
-          path = '/api/v2/blacklists/tokens'
-          get(path)
+        attr_reader :blacklists_path
+
+        # Retrieves the jti and aud of all tokens in the blacklist.
+        # @see https://auth0.com/docs/api/v2#!/Blacklists/get_tokens
+        # @param aud [string] The JWT's aud claim. The client_id of the client for which it was issued
+        #
+        # @return [json] Returns the blacklisted tokens
+        #
+        def blacklisted_tokens(aud = nil)
+          request_params = {
+            aud: aud
+          }
+          get(blacklists_path, request_params)
         end
 
-        # https://auth0.com/docs/apiv2#!/blacklists/post_tokens
+        # Adds the token identified by the jti to a blacklist for the tenant.
+        # @see https://auth0.com/docs/api/v2#!/blacklists/post_tokens
+        # @param jti [string] The jti of the JWT to blacklist
+        # @param aud [string] The JWT's aud claim. The client_id of the client for which it was issued
+        # @return [json] Returns the blacklisted token
+        #
         def add_token_to_blacklist(jti, aud = nil)
+          fail Auth0::MissingParameter, 'Must specify a valid JTI' if jti.to_s.empty?
           request_params = {
             jti: jti,
             aud: aud
           }
-          path = '/api/v2/blacklists/tokens'
-          post(path, request_params)
+          post(blacklists_path, request_params)
+        end
+
+        private
+
+        # Blacklists API path
+        def blacklists_path
+          @blacklists_path ||= '/api/v2/blacklists/tokens'
         end
       end
     end

lib/auth0/api/v2/clients.rb

@@ -1,40 +1,81 @@
 module Auth0
   module Api
     module V2
-      # https://auth0.com/docs/apiv2#!/clients
+      # Methods to use the client endpoints
       module Clients
-        # https://auth0.com/docs/apiv2#!/clients/get_clients
-        def clients(options = {})
-          path = '/api/v2/clients'
-          get(path, options)
+        attr_reader :clients_path
+
+        # Retrieves a list of all client applications. Accepts a list of fields to include or exclude.
+        # @see https://auth0.com/docs/api/v2#!/clients/get_clients
+        # @param fields [string] A comma separated list of fields to include or exclude from the result.
+        # @param include_fields [boolean] if the fields specified are to be included in the result, false otherwise
+        #
+        # @return [json] Returns the clients applications.
+        def clients(fields: nil, include_fields: nil)
+          include_fields = true if !fields.nil? && include_fields.nil?
+          request_params = {
+            fields: fields,
+            include_fields: include_fields
+          }
+          get(clients_path, request_params)
         end
         alias_method :get_clients, :clients
 
-        # https://auth0.com/docs/apiv2#!/clients/post_clients
+        # Creates a new client application.
+        # @see https://auth0.com/docs/api/v2#!/clients/post_clients
+        # @param name [string] The name of the client. Must contain at least one character. Does not allow '<' or '>'
+        # @param options [hash] The Hash options used to define the client's properties.
+        # @return  [json] Returns the created client application.
         def create_client(name, options = {})
+          fail Auth0::MissingParameter, 'Must specify a valid client name' if name.to_s.empty?
           request_params = Hash[options.map { |(k, v)| [k.to_sym, v] }]
           request_params[:name] = name
-          path = '/api/v2/clients'
-          post(path, request_params)
+          post(clients_path, request_params)
         end
 
-        # https://auth0.com/docs/apiv2#!/clients/get_clients_by_id
-        def client(client_id, options = {})
-          path = "/api/v2/clients/#{client_id}"
-          get(path, options)
+        # Retrieves a client by its id.
+        # @see https://auth0.com/docs/api/v2#!/Clients/get_clients_by_id
+        # @param client_id [string] The id of the client to retrieve
+        # @param fields [string] A comma separated list of fields to include or exclude from the result.
+        # @param include_fields [boolean] If the fields specified are to be included in the result, false otherwise
+        # @return  [json] Returns the requested client application.
+        def client(client_id, fields: nil, include_fields: nil)
+          fail Auth0::MissingClientId, 'Must specify a client id' if client_id.to_s.empty?
+          include_fields = true if !fields.nil? && include_fields.nil?
+          request_params = {
+            fields: fields,
+            include_fields: include_fields
+          }
+          path = "#{clients_path}/#{client_id}"
+          get(path, request_params)
         end
 
-        # https://auth0.com/docs/apiv2#!/clients/delete_clients_by_id
+        # Deletes a client and all its related assets (like rules, connections, etc) given its id.
+        # @see https://auth0.com/docs/api/v2#!/Clients/delete_clients_by_id
+        # @param client_id [string] The id of the client to delete
         def delete_client(client_id)
-          path = "/api/v2/clients/#{client_id}"
+          fail Auth0::MissingClientId, 'Must specify a client id' if client_id.to_s.empty?
+          path = "#{clients_path}/#{client_id}"
           delete(path)
         end
 
-        # https://auth0.com/docs/apiv2#!/clients/patch_clients_by_id
+        # Updates a client.
+        # @see https://auth0.com/docs/api/v2#!/Clients/patch_clients_by_id
+        # @param client_id [string] The id of the client to update
+        # @param options [hash] The Hash options used to define the client's properties.
         def patch_client(client_id, options)
-          path = "/api/v2/clients/#{client_id}"
+          fail Auth0::MissingClientId, 'Must specify a client id' if client_id.to_s.empty?
+          fail Auth0::MissingParameter, 'Must specify a valid body' if options.to_s.empty?
+          path = "#{clients_path}/#{client_id}"
           patch(path, options)
         end
+
+        private
+
+        # Clients API path
+        def clients_path
+          @clients_path ||= '/api/v2/clients'
+        end
       end
     end
   end