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,16 +1,30 @@
 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
+        # 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)
           path = '/api/v2/blacklists/tokens'
-          get(path)
+          request_params = {
+            aud: aud
+          }
+          get(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, 'you must specify a valid JTI' if jti.to_s.empty?
           request_params = {
             jti: jti,
             aud: aud

lib/auth0/api/v2/clients.rb

@@ -1,37 +1,71 @@
 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 = {})
+        # 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
+          }
           path = '/api/v2/clients'
-          get(path, options)
+          get(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, 'you 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)
         end
 
-        # https://auth0.com/docs/apiv2#!/clients/get_clients_by_id
-        def client(client_id, 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, 'you 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 = "/api/v2/clients/#{client_id}"
-          get(path, options)
+          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)
+          fail Auth0::MissingClientId, 'you must specify a client id' if client_id.to_s.empty?
           path = "/api/v2/clients/#{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)
+          fail Auth0::MissingClientId, 'you must specify a client id' if client_id.to_s.empty?
+          fail Auth0::MissingParameter, 'you must specify a valid body' if options.to_s.empty?
           path = "/api/v2/clients/#{client_id}"
           patch(path, options)
         end

lib/auth0/api/v2/connections.rb

@@ -1,8 +1,16 @@
 module Auth0
   module Api
     module V2
-      # https://auth0.com/docs/api/v2#!/Connections
+      # Methods to use the connections endpoints
       module Connections
+        # Retrieves every connection matching the specified strategy. All connections are retrieved if no strategy is
+        # being specified. Accepts a list of fields to include or exclude in the resulting list of connection objects.
+        # @see https://auth0.com/docs/api/v2#!/Connections/get_connections
+        # @param strategy [string] Provide a type of strategy to only retrieve connections with that strategy
+        # @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 existing connections matching the strategy.
         def connections(strategy: nil, fields: nil, include_fields: true)
           request_params = {
             strategy: strategy,
@@ -14,13 +22,27 @@ def connections(strategy: nil, fields: nil, include_fields: true)
         end
         alias_method :get_connections, :connections
 
+        # Creates a new connection according to the JSON object received in body.
+        # @see https://auth0.com/docs/api/v2#!/Connections/post_connections
+        # @param body [hash] The Hash options used to define the conecctions's properties.
+        #
+        # @return  [json] Returns the created connection.
         def create_connection(body)
+          fail Auth0::InvalidParameter, 'Must specify a body to create a connection' if body.to_s.empty?
           path = '/api/v2/connections'
           request_params = body
           post(path, request_params)
         end
 
+        # Retrieves a connection by its id.
+        # @see https://auth0.com/docs/api/v2#!/Connections/get_connections_by_id
+        # @param connection_id [string] The id of the connection 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 matching connection
         def connection(connection_id, fields: nil, include_fields: true)
+          fail Auth0::InvalidParameter, 'Must supply a valid connection id' if connection_id.to_s.empty?
           path = "/api/v2/connections/#{connection_id}"
           request_params = {
             fields:         fields,
@@ -29,14 +51,37 @@ def connection(connection_id, fields: nil, include_fields: true)
           get(path, request_params)
         end
 
+        # Deletes a connection and all its users.
+        # @see https://auth0.com/docs/api/v2#!/Connections/delete_connections_by_id
+        # @param connection_id [string] The id of the connection to delete
         def delete_connection(connection_id)
-          fail Auth0::MissingConnectionId, 'you must specify a connection id' if connection_id.to_s.empty?
+          fail Auth0::InvalidParameter, 'Must supply a valid connection id' if connection_id.to_s.empty?
           path = "/api/v2/connections/#{connection_id}"
           delete(path)
         end
 
+        # Deletes a specified connection user by its email (currently only database connections are supported and you
+        # cannot delete all users from specific connection).
+        # @see https://auth0.com/docs/api/v2#!/Connections/delete_users
+        # @param connection_id [string] The id of the connection
+        # @param user_email [string] The email of the user to delete
+        #
+        # @return  [json] Returns the updated connection.
+        def delete_connection_user(connection_id, user_email)
+          fail Auth0::InvalidParameter, 'Must supply a valid connection id' if connection_id.to_s.empty?
+          fail Auth0::InvalidParameter, 'Must supply a valid user email' if user_email.to_s.empty?
+          path = "/api/v2/connections/#{connection_id}/users?email=#{user_email}"
+          delete(path)
+        end
+
+        # Updates a connection. Updates the fields specified in the body parameter.
+        # @see https://auth0.com/docs/api/v2#!/Connections/patch_connections_by_id
+        # @param connection_id [string] The id of the connection to delete
+        # @param body [hash] The Hash options used to update the conecctions's properties.
+        #
+        # @return  [json] Returns the updated connection.
         def update_connection(connection_id, body)
-          fail Auth0::MissingConnectionId, 'you must specify a connection id' if connection_id.to_s.empty?
+          fail Auth0::InvalidParameter, 'Must supply a valid connection id' if connection_id.to_s.empty?
           path = "/api/v2/connections/#{connection_id}"
           patch(path, body)
         end