auth0 3.6.1 → 4.0.0

data/lib/auth0/api/v2/users.rb

@@ -1,71 +1,160 @@
 module Auth0
   module Api
     module V2
-      #https://auth0.com/docs/apiv2#!/users
+      # Methods to use the users endpoints
       module Users
-        #https://auth0.com/docs/apiv2#!/users/get_users
-        def users( per_page: nil, page: nil, include_totals: nil, sort: nil, connection: nil, fields: nil, q: nil )
+        attr_reader :users_path
+
+        # Retrieves a list of existing users.
+        # @see https://auth0.com/docs/api/v2#!/Users/get_users
+        # @param per_page [integer] The amount of entries per page. Default: 50. Max value: 100
+        # @param page [integer]  The page number. Zero based
+        # @param include_totals [boolean] true if a query summary must be included in the result
+        # @param sort [string] The field to use for sorting. 1 == ascending and -1 == descending
+        # @param connection [string] Connection filter
+        # @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.
+        # @param q [string] Query in Lucene query string syntax. Only fields in app_metadata, user_metadata or the
+        # normalized user profile are searchable.
+        #
+        # @return [json] The list of existing users.
+        def users(options = {})
           request_params = {
-            per_page:       per_page,
-            page:           page,
-            include_totals: include_totals,
-            sort:           sort,
-            connection:     connection,
-            fields:         fields,
-            q:              q
+            per_page:       options.fetch(:per_page, nil),
+            page:           options.fetch(:page, nil),
+            include_totals: options.fetch(:include_totals, nil),
+            sort:           options.fetch(:sort, nil),
+            connection:     options.fetch(:connection, nil),
+            fields:         options.fetch(:fields, nil),
+            include_fields: options.fetch(:include_fields, nil),
+            q:              options.fetch(:q, nil)
           }
-
-          if request_params[:q]
-            request_params[:search_engine] = :v2
-          end
-
-          path = "/api/v2/users"
-          get(path, request_params)
+          request_params[:search_engine] = :v2 if request_params[:q]
+          get(users_path, request_params)
         end
-        alias :get_users :users
+        alias_method :get_users, :users
 
-        #https://auth0.com/docs/apiv2#!/users/post_users
-        def create_user(name, options={})
-          path = "/api/v2/users"
-          request_params = Hash[options.map{|(k,v)| [k.to_sym,v]}]
+        # Creates a new user according to optional parameters received.
+        # The attribute connection is always mandatory but depending on the type of connection you are using there
+        # could be others too. For instance, Auth0 DB Connections require email and password.
+        # @see https://auth0.com/docs/api/v2#!/Users/post_users
+        # @param name [string] the user name
+        # @param connection [string] The connection the user belongs to
+        #
+        # @return [json]
+        def create_user(name, options = {})
+          request_params = Hash[options.map { |(k, v)| [k.to_sym, v] }]
           request_params[:name] = name
-          post(path, request_params)
+          post(users_path, request_params)
         end
 
-        #https://auth0.com/docs/apiv2#!/users/delete_users
+        # Delete all users - USE WITH CAUTION
+        # @see https://auth0.com/docs/api/v2#!/Users/delete_users
         def delete_users
-          path = "/api/v2/users"
-          delete(path)
+          delete(users_path)
         end
 
-        #https://auth0.com/docs/apiv2#!/users/get_users_by_id
-        def user(user_id, fields: nil)
-          path = "/api/v2/users/" + user_id.to_s
+        # Retrieves a user given a user_id
+        # @see https://auth0.com/docs/api/v2#!/Users/get_users_by_id
+        # @param user_id [string] The user_id of the user 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] the user with the given user_id if exists
+        def user(user_id, fields: nil, include_fields: true)
+          fail Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+          path = "#{users_path}/#{user_id}"
           request_params = {
             fields:         fields,
+            include_fields: include_fields
           }
           get(path, request_params)
         end
 
-        #https://auth0.com/docs/apiv2#!/users/delete_users_by_id
+        # Deletes a single user given its id
+        # @see https://auth0.com/docs/api/v2#!/Users/delete_users_by_id
+        # @param user_id [string] The user_id of the user to delete
         def delete_user(user_id)
-          raise Auth0::MissingUserId, "Must supply a valid user_id" if user_id.nil? or user_id.to_s.empty?
-          path = "/api/v2/users/" + user_id.to_s
+          fail Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+          path = "#{users_path}/#{user_id}"
           delete(path)
         end
 
-
-        #https://auth0.com/docs/apiv2#!/users/patch_users_by_id
-        def patch_user(user_id, options)
-          path = "/api/v2/users/" + user_id
-          patch(path, options)
+        # Updates a user with the object's properties received in the optional parameters.
+        # These are the attributes that can be updated at the root level:
+        # blocked, email_verified, email, verify_email, password, phone_number, phone_verified,
+        # verify_password, user_metadata, app_metadata, username
+        # Some considerations:
+        # The properties of the new object will replace the old ones.
+        # The metadata fields are an exception to this rule (user_metadata and app_metadata). These properties are
+        # merged instead of being replaced but be careful, the merge only occurs on the first level.
+        # If you are updating email_verified, phone_verified, username or password you need to specify the connection
+        # property too.
+        # If your are updating email or phone_number you need to specify the connection and the client_id properties.
+        # @see https://auth0.com/docs/api/v2#!/Users/patch_users_by_id
+        # @param user_id [string] The user_id of the user to update.
+        # @param body [hash] The optional parametes to update
+        #
+        # @return [json] the updated user
+        def patch_user(user_id, body)
+          fail Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+          fail Auth0::InvalidParameter, 'Must supply a valid body' if body.to_s.empty?
+          path = "#{users_path}/#{user_id}"
+          patch(path, body)
         end
 
-        #https://auth0.com/docs/apiv2#!/users/delete_multifactor_by_provider
+        # Delete a user's multifactor provider
+        # @see https://auth0.com/docs/api/v2#!/Users/delete_multifactor_by_provider
+        # @param user_id [string] The user_id of the user to delete
+        # @param provider_name [string] The multifactor provider. Supported values 'duo' or 'google-authenticator'
         def delete_user_provider(user_id, provider_name)
-          path = "/api/v2/users/#{user_id}/multifactor/#{provider_name}"
+          fail Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+          fail Auth0::InvalidParameter, 'Must supply a valid provider name' if provider_name.to_s.empty?
+          path = "#{users_path}/#{user_id}/multifactor/#{provider_name}"
           delete(path)
         end
+
+        # Links the account specified in the body (secondary account) to the account specified by the id param
+        # of the URL (primary account).
+        # 1. With the authenticated primary account's JWT in the Authorization header, which has the
+        # update:current_user_identities scope. In this case only the link_with param is required in the body,
+        # containing the JWT obtained upon the secondary account's authentication.
+        # 2. With an API V2 generated token with update:users scope. In this case you need to send provider and user_id
+        # in the body. Optionally you can also send the connection_id param which is suitable for identifying a
+        # particular database connection for the 'auth0' provider.
+        # @see https://auth0.com/docs/api/v2#!/Users/post_identities
+        # @param user_id [string] The user_id of the primary identity where you are linking the secondary account to.
+        # @param body [string] the options to link the account to.
+        #
+        # @return [json] the new array of the primary account identities.
+        def link_user_account(user_id, body)
+          fail Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+          fail Auth0::InvalidParameter, 'Must supply a valid body' if body.to_s.empty?
+          path = "#{users_path}/#{user_id}/identities"
+          post(path, body)
+        end
+
+        # Unlink a user account
+        # @see https://auth0.com/docs/api/v2#!/Users/delete_provider_by_user_id
+        # @param user_id [string] The user_id of the user identity.
+        # @param provider [string] The type of identity provider.
+        # @param secondary_user_id [string] The unique identifier for the user for the identity.
+        #
+        # @return [json] the array of the unlinked account identities.
+        def unlink_users_account(user_id, provider, secondary_user_id)
+          fail Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+          fail Auth0::MissingUserId, 'Must supply a valid secondary user_id' if secondary_user_id.to_s.empty?
+          fail Auth0::InvalidParameter, 'Must supply a valid provider' if provider.to_s.empty?
+          path = "#{users_path}/#{user_id}/identities/#{provider}/#{secondary_user_id}"
+          delete(path)
+        end
+
+        private
+
+        # Users API path
+        def users_path
+          @users_path ||= '/api/v2/users'
+        end
       end
     end
   end

data/lib/auth0/client.rb

@@ -1,7 +1,9 @@
-# Main class
-# All Api calls are suposed to return hashes, but delete actions return strings.
-class Auth0::Client
-  include Auth0::Mixins
-  include HTTParty
-  base_uri "http://auth0.com"
+module Auth0
+  # Main class
+  # All Api calls are suposed to return hashes, but delete actions return strings.
+  class Client
+    include Auth0::Mixins
+    include HTTMultiParty
+    base_uri 'http://auth0.com'
+  end
 end

data/lib/auth0/exception.rb

@@ -2,27 +2,33 @@ module Auth0
   # Default exception in namespace of Auth0
   # if you want to catch all exceptions, then you should use this one.
   # Network exceptions are not included
-  class Exception     < StandardError;    end
+  class Exception < StandardError; end
+  # exception for unauthorized requests, if you see it,
+  # probably Bearer Token is not set correctly
+  class Unauthorized < Auth0::Exception; end
+  # exception for not found resource, you query for an
+  # unexistent resource, or wrong path
+  class NotFound < Auth0::Exception; end
+  # exception for unknown error
+  class Unsupported < Auth0::Exception; end
+  # exception for server error
+  class ServerError < Auth0::Exception; end
+  # exception for incorrect request, you've sent wrong params
+  class BadRequest < Auth0::Exception; end
+  # exception for unset user_id, this might cause removal of
+  # all users, or other unexpected behaviour
+  class MissingUserId < Auth0::Exception; end
+  # exception for unset client_id
+  class MissingClientId < Auth0::Exception; end
+  # exception for an unset parameter
+  class MissingParameter < Auth0::Exception; end
+  # Api v2 access denied
+  class AccessDenied < Auth0::Exception; end
+  # Invalid parameter passed, e.g. empty where ID is required
+  class InvalidParameter < Auth0::Exception; end
+  # Invalid Auth0 credentials either client_id/secret for API v1
+  # or JWT for API v2/
+  class InvalidCredentials < Auth0::Exception; end
+  # Invalid Auth0 API namespace
+  class InvalidApiNamespace < Auth0::Exception; end
 end
-# exception for unauthorized requests, if you see it, probably Bearer Token is not set correctly
-class Auth0::Unauthorized  < Auth0::Exception; end
-# exception for not found resource, you query for an unexistent resource, or wrong path
-class Auth0::NotFound      < Auth0::Exception; end
-# exception for unknown error
-class Auth0::Unsupported   < Auth0::Exception; end
-# exception for server error
-class Auth0::ServerError   < Auth0::Exception; end
-# exception for incorrect request, you've sent wrong params
-class Auth0::BadRequest    < Auth0::Exception; end
-# exception for unset user_id, this might cause removal of all users, or other unexpected bahaviour
-class Auth0::MissingUserId < Auth0::Exception; end
-# exception for an unset connection_id
-class Auth0::MissingConnectionId < Auth0::Exception; end
-# Api v2 access denied
-class Auth0::AccessDenied  < Auth0::Exception; end
-# Invalid parameter passed, e.g. empty where ID is required
-class Auth0::InvalidParameter < Auth0::Exception; end
-# Invalid Auth0 credentials either client_id/secret for API v1 or JWT for API v2/
-class Auth0::InvalidCredentials < Auth0::Exception; end
-# Invalid Auth0 API namespace
-class Auth0::InvalidApiNamespace < Auth0::Exception; end

data/lib/auth0/mixins.rb

@@ -1,12 +1,14 @@
-require 'httparty'
+require 'httmultiparty'
 require 'uri'
-require "auth0/mixins/httparty_proxy"
-require "auth0/mixins/initializer"
-require "auth0/api/authentication_endpoints"
-require "auth0/api/v1"
-require "auth0/api/v2"
-# Collecting dependencies here
-module Auth0::Mixins
-  include Auth0::Mixins::HTTPartyProxy
-  include Auth0::Mixins::Initializer
+require 'auth0/mixins/httparty_proxy'
+require 'auth0/mixins/initializer'
+require 'auth0/api/authentication_endpoints'
+require 'auth0/api/v1'
+require 'auth0/api/v2'
+module Auth0
+  # Collecting dependencies here
+  module Mixins
+    include Auth0::Mixins::HTTPartyProxy
+    include Auth0::Mixins::Initializer
+  end
 end

data/lib/auth0/mixins/httparty_proxy.rb

@@ -1,14 +1,17 @@
 module Auth0
   module Mixins
-    # here's the proxy for HTTParty, we're building all request on that gem for now, if you want to feel free to use your own http client
+    # here's the proxy for HTTParty, we're building all request on that gem
+    # for now, if you want to feel free to use your own http client
     module HTTPartyProxy
       # proxying requests from instance methods to HTTParty class methods
-      %i(get post put patch delete).each do |method|
-        define_method(method) do |path, body={}|
+      %i(get post post_file put patch delete).each do |method|
+        define_method(method) do |path, body = {}|
           safe_path = URI.escape(path)
-          body = body.delete_if {|k,v| v.nil? }
+          body = body.delete_if { |_, v| v.nil? }
           if method == :get
             result = self.class.send(method, safe_path, query: body)
+          elsif method == :post_file
+            result = self.class.send(:post, safe_path, body: body, detect_mime_type: true)
           else
             result = self.class.send(method, safe_path, body: body.to_json)
           end
@@ -20,13 +23,13 @@ module Auth0
           end
           case result.code
           when 200...226 then response_body
-          when 400 then raise Auth0::BadRequest, response_body
-          when 401 then raise Auth0::Unauthorized, response_body
-          when 403 then raise Auth0::AccessDenied, response_body
-          when 404 then raise Auth0::NotFound, response_body
-          when 500 then raise Auth0::ServerError, response_body
+          when 400 then fail Auth0::BadRequest, response_body
+          when 401 then fail Auth0::Unauthorized, response_body
+          when 403 then fail Auth0::AccessDenied, response_body
+          when 404 then fail Auth0::NotFound, response_body
+          when 500 then fail Auth0::ServerError, response_body
           else
-            raise Auth0::Unsupported, response_body
+            fail Auth0::Unsupported, response_body
           end
         end
       end

data/lib/auth0/mixins/initializer.rb

@@ -6,19 +6,14 @@ module Auth0
       # accepts hash as parameter
       # you can get all required fields from here: https://auth0.com/docs/auth-api
       #
-      # To run using api v2, pass api_version: 2 when creating a client
+      # By Default API v2
       def initialize(config)
-        options = Hash[config.map{|(k,v)| [k.to_sym,v]}]
-        domain = api_domain options
-        raise InvalidApiNamespace, "Api namespace must supply an API domain" if domain.nil?
-        self.class.base_uri "https://#{domain}"
+        options = Hash[config.map { |(k, v)| [k.to_sym, v] }]
+        self.class.base_uri base_url(options)
         self.class.headers client_headers(config)
-        self.extend Auth0::Api::AuthenticationEndpoints
-        @client_id      = options[:client_id]
-        initialize_v2(options) if api_v2?(options)
-        initialize_v1(options) if api_v1?(options)
-        raise InvalidCredentials, "Must supply a valid API token" if @token.nil?
-        self.class.headers "Authorization" => "Bearer #{@token}"
+        extend Auth0::Api::AuthenticationEndpoints
+        @client_id = options[:client_id]
+        initialize_api(options)
       end
 
       # including initializer in top of klass
@@ -28,14 +23,26 @@ module Auth0
 
       private
 
+      def initialize_api(options)
+        api_v1?(options) ? initialize_v1(options) : initialize_v2(options)
+        fail InvalidCredentials, 'Must supply a valid API token' if @token.nil?
+        self.class.headers 'Authorization' => "Bearer #{@token}"
+      end
+
+      def base_url(options)
+        @domain = options[:domain] || options[:namespace]
+        fail InvalidApiNamespace, 'Api namespace must supply an API domain' if @domain.to_s.empty?
+        "https://#{@domain}"
+      end
+
       def client_headers(config)
-        client_info = JSON.dump({name: 'ruby-auth0', version: Auth0::VERSION})
+        client_info = JSON.dump(name: 'ruby-auth0', version: Auth0::VERSION)
 
         headers = {
           'Content-Type' => 'application/json'
         }
 
-        if !config[:opt_out_sdk_info]
+        unless config[:opt_out_sdk_info]
           headers['User-Agent'] = "Ruby/#{RUBY_VERSION}"
           headers['Auth0-Client'] = Base64.urlsafe_encode64(client_info)
         end
@@ -43,32 +50,23 @@ module Auth0
         headers
       end
 
-      def api_domain(options)
-        options[:domain] || options[:namespace]
-      end
-
       def initialize_v2(options)
-        self.extend Auth0::Api::V2
+        extend Auth0::Api::V2
         @token = options[:access_token] || options[:token]
       end
 
       def initialize_v1(options)
-        self.extend Auth0::Api::V1
-        @client_secret  = options[:client_secret]
-        raise InvalidCredentials, "Invalid API v1 client_id and client_secret" if @client_id.nil? or @client_secret.nil?
+        extend Auth0::Api::V1
+        @client_secret = options[:client_secret]
+        fail InvalidCredentials, 'Invalid API v1 client_id and client_secret' if @client_id.nil? || @client_secret.nil?
         @token = obtain_access_token
       end
 
-      def api_v2?(options)
-        options[:protocols].to_s.include?("v2") or options[:api_version] === 2
-      end
-
       def api_v1?(options)
         version = options[:api_version] || 1
         protocol = options[:protocols].to_s
-        not protocol.include?("v2") and (protocol.include?("v1") or version === 1)
+        !protocol.include?('v2') && (protocol.include?('v1') || version == 1)
       end
-
     end
   end
 end

data/lib/auth0/version.rb

@@ -1,4 +1,4 @@
+# current version of gem
 module Auth0
-  # current version of gem
-  VERSION = "3.6.1"
+  VERSION = '4.0.0'
 end

data/spec/integration/lib/auth0/api/v1/api_clients_spec.rb

@@ -1,14 +1,12 @@
-require "spec_helper"
+require 'spec_helper'
 describe Auth0::Api::V1::Clients do
-
   let(:client) { Auth0Client.new(v1_creds) }
   let(:global_client) { Auth0Client.new(v1_global_creds) }
   let(:client_name) { "client#{entity_suffix}" }
 
   it { expect(client.clients).to_not be_empty }
 
-  it { expect {client.create_client(client_name)}.to raise_error(Auth0::Unauthorized) }
+  it { expect { client.create_client(client_name) }.to raise_error(Auth0::Unauthorized) }
 
   it { expect(global_client.create_client(client_name)).to_not be_nil }
-
 end