auth0 3.6.1 → 4.0.0

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

@@ -1,26 +1,49 @@
 module Auth0
   module Api
     module V2
+      # Methods to use the connections endpoints
       module Connections
+        attr_reader :connections_path
+
+        # 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,
             fields: fields,
             include_fields: include_fields
           }
-          path = "/api/v2/connections"
-          get(path, request_params)
+          get(connections_path, request_params)
         end
-        alias :get_connections :connections
+        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)
-          path = "/api/v2/connections"
+          fail Auth0::InvalidParameter, 'Must specify a body to create a connection' if body.to_s.empty?
           request_params = body
-          post(path, request_params )
+          post(connections_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)
-          path = "/api/v2/connections/" + connection_id.to_s
+          fail Auth0::InvalidParameter, 'Must supply a valid connection id' if connection_id.to_s.empty?
+          path = "#{connections_path}/#{connection_id}"
           request_params = {
             fields:         fields,
             include_fields: include_fields
@@ -28,17 +51,47 @@ module Auth0
           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)
-          raise Auth0::MissingConnectionId, "you must specify a connection id" if connection_id.to_s.empty?
-          path = "/api/v2/connections/#{connection_id}"
+          fail Auth0::InvalidParameter, 'Must supply a valid connection id' if connection_id.to_s.empty?
+          path = "#{connections_path}/#{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 = "#{connections_path}/#{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)
-          raise Auth0::MissingConnectionId, "you must specify a connection id" if connection_id.to_s.empty?
-          path = "/api/v2/connections/" + connection_id.to_s
+          fail Auth0::InvalidParameter, 'Must supply a valid connection id' if connection_id.to_s.empty?
+          path = "#{connections_path}/#{connection_id}"
           patch(path, body)
         end
+
+        private
+
+        # Connections API path
+        def connections_path
+          @connections_path ||= '/api/v2/connections'
+        end
       end
     end
   end

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

@@ -0,0 +1,58 @@
+module Auth0
+  module Api
+    module V2
+      # Methods to use the connections endpoints
+      module Emails
+        attr_reader :email_path
+
+        # Get all the email providers.
+        # @see https://auth0.com/docs/api/v2#!/Emails/get_provider
+        # @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 email providers.
+        def get_provider(fields: nil, include_fields: nil)
+          request_params = {
+            fields:           fields,
+            include_fields:   include_fields
+          }
+          get(email_path, request_params)
+        end
+
+        # Configure a new email provider.
+        # @see https://auth0.com/docs/api/v2#!/Emails/post_provider
+        # @param body [hash] The Hash options used to spcify the email provider's properties.
+        #
+        # @return [json] Returns the created email provider.
+        def configure_provider(body)
+          fail Auth0::InvalidParameter, 'Must supply a valid body to create an email provider' if body.to_s.empty?
+          post(email_path, body)
+        end
+
+        # Deletes the configured email provider.
+        # @see https://auth0.com/docs/api/v2#!/Emails/delete_provider
+        #
+        # @return [json] Returns the created email provider.
+        def delete_provider
+          delete(email_path)
+        end
+
+        # Updates the configured email provider.
+        # @see https://auth0.com/docs/api/v2#!/Emails/patch_provider
+        # @param body [hash] The Hash options used to spcify the email provider's properties.
+        #
+        # @return [json] Returns the updated email provider.
+        def update_provider(body)
+          fail Auth0::InvalidParameter, 'Must supply a valid body to update an email provider' if body.to_s.empty?
+          patch(email_path, body)
+        end
+
+        private
+
+        def email_path
+          @email_path ||= '/api/v2/emails/provider'
+        end
+      end
+    end
+  end
+end

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

@@ -1,18 +1,55 @@
 module Auth0
   module Api
     module V2
-      # https://auth0.com/docs/apiv2#!/jobs
+      # Methods to use the jobs endpoints
       module Jobs
-        #https://auth0.com/docs/apiv2#!/jobs/get_jobs_by_job_id
+        attr_reader :jobs_path
+
+        # Retrieves a job. Useful to check its status.
+        # @see https://auth0.com/docs/api/v2#!/Jobs/get_jobs_by_job_id
+        # @param job_id [string] The id of the job
+        #
+        # @return [json] the job status and properties
         def get_job(job_id)
-          path = "/api/v2/jobs/#{job_id}"
+          fail Auth0::InvalidParameter, 'Must specify a job id' if job_id.to_s.empty?
+          path = "#{jobs_path}/#{job_id}"
           get(path)
         end
 
-        # HTTParty doesn't support multipart upload, will move this functionality to a separate PR
-        # https://auth0.com/docs/apiv2#!/jobs/post_users_imports
-        def create_job(users_file, connection_name)
-          raise NotImplementedError
+        # Imports users to a connection from a file using a long running job.
+        # Important: The documentation for the file format is at https://docs.auth0.com/bulk-import.
+        # @see https://auth0.com/docs/api/v2#!/Jobs/post_users_imports
+        # @param users_file [file] A file containing the users to import
+        # @param connection_id [string] The connection id of the connection to which users will be inserted
+        #
+        # @return [json] the job status and properties
+        def import_users(users_file, connection_id)
+          fail Auth0::InvalidParameter, 'Must specify a valid file' if users_file.to_s.empty?
+          fail Auth0::InvalidParameter, 'Must specify a connection_id' if connection_id.to_s.empty?
+          request_params = {
+            users: users_file,
+            connection_id: connection_id
+          }
+          path = "#{jobs_path}/users-imports"
+          post_file(path, request_params)
+        end
+
+        # Send an email to the specified user that asks them to click a link to verify their email address.
+        # @see https://auth0.com/docs/api/v2#!/Jobs/post_verification_email
+        # @param user_id [string] The user_id of the user to whom the email will be sent
+        #
+        # @return [json] the job status and properties
+        def send_verification_email(user_id)
+          fail Auth0::InvalidParameter, 'Must specify a user id' if user_id.to_s.empty?
+          path = "#{jobs_path}/verification-email"
+          post(path, user_id)
+        end
+
+        private
+
+        # Jobs API path
+        def jobs_path
+          @jobs_path ||= '/api/v2/jobs'
         end
       end
     end

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

@@ -0,0 +1,104 @@
+module Auth0
+  module Api
+    module V2
+      # Methods to use the rules endpoints
+      module Rules
+        attr_reader :rules_path
+
+        # Retrieves a list of all rules. Accepts a list of fields to include or exclude.
+        # The enabled parameter can be specified to get enabled or disabled rules.
+        # The rule's stage of executing could be set to the following values login_success,
+        # login_failure or pre_authorize
+        # @see https://auth0.com/docs/api/v2#!/Rules/get_rules
+        # @param enabled [boolean]  If provided retrieves rules that match the value, otherwise all rules are retrieved
+        # @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 stage [string]  Retrieves rules that match the execution stage (defaults to login_success)
+        #
+        # @return [json] Returns the existing rules.
+        def rules(enabled: nil, fields: nil, include_fields: nil, stage: nil)
+          request_params = {
+            enabled:          enabled,
+            fields:           fields,
+            include_fields:   include_fields,
+            stage:            stage
+          }
+          get(rules_path, request_params)
+        end
+
+        alias_method :get_rules, :rules
+
+        # Retrieves a rule by its ID. Accepts a list of fields to include or exclude in the result.
+        # @see https://auth0.com/docs/api/v2#!/Rules/get_rules_by_id
+        # @param rule_id [string]   The id of the rule 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 rule.
+        def rule(rule_id, fields: nil, include_fields: nil)
+          fail Auth0::InvalidParameter, 'Must supply a valid rule id' if rule_id.to_s.empty?
+          path = "#{rules_path}/#{rule_id}"
+          request_params = {
+            fields:   fields,
+            include_fields:   include_fields
+          }
+          get(path, request_params)
+        end
+
+        alias_method :get_rule, :rule
+
+        # Creates a new rule according to the JSON object received in body.
+        # @see https://auth0.com/docs/api/v2#!/Rules/post_rules
+        # @param name [string]   The name of the rule. Can only contain alphanumeric characters, spaces and '-'.
+        # @param script [string] A script that contains the rule's code
+        # @param order [integer] The rule's order in relation to other rules. A rule with a lower order than another rule
+        # executes first. If no order is provided it will automatically be one greater than the current maximum
+        # @param enabled [string] true if the rule is enabled, false otherwise
+        # @param stage [string] The rule's execution stage 'login_success' or 'login_failure' or 'pre_authorize' or
+        # 'user_registration' or 'user_blocked'
+        #
+        # @return [json] Returns the rule.
+        def create_rule(name, script, order = nil, enabled = true, stage = 'login_success')
+          fail Auth0::InvalidParameter, 'Must supply a valid name' if name.to_s.empty?
+          fail Auth0::InvalidParameter, 'Must supply a valid script' if script.to_s.empty?
+          request_params = {
+            name: name,
+            enabled: enabled,
+            script: script,
+            order: order,
+            stage: stage
+          }
+          post(rules_path, request_params)
+        end
+
+        # Updates a rule.
+        # @see https://auth0.com/docs/api/v2#!/Rules/patch_rules_by_id
+        # @param rule_id [string] The id of the rule to retrieve
+        # @param fields_to_update [hash] The Hash fields_to_update used to define the rule's properties.
+        # @return [json] Returns the updated rule.
+        def update_rule(rule_id, fields_to_update = {})
+          fail Auth0::InvalidParameter, 'Must supply a valid rule id' if rule_id.to_s.empty?
+
+          path = "#{rules_path}/#{rule_id}"
+          patch(path, fields_to_update)
+        end
+
+        # Deletes a rule.
+        # @see https://auth0.com/docs/api/v2#!/Rules/delete_rules_by_id
+        # @param rule_id [string] The id of the rule to retrieve
+        def delete_rule(rule_id)
+          fail Auth0::InvalidParameter, 'Must supply a valid rule id' if rule_id.to_s.empty?
+          path = "#{rules_path}/#{rule_id}"
+          delete(path)
+        end
+
+        private
+
+        # Rules API path
+        def rules_path
+          @rules_path ||= '/api/v2/rules'
+        end
+      end
+    end
+  end
+end

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

@@ -1,23 +1,40 @@
 module Auth0
   module Api
     module V2
-      # https://auth0.com/docs/apiv2#!/stats
+      # Methods to use the stats endpoints
       module Stats
-        #https://auth0.com/docs/apiv2#!/stats/get_active_users
+        attr_reader :stats_path
+
+        # Gets the active users count (logged in during the last 30 days).
+        # @see https://auth0.com/docs/api/v2#!/Stats/get_active_users
+        #
+        # @return [integer] Returns numbers
         def active_users
-          path = "/api/v2/stats/active-users"
+          path = "#{stats_path}/active-users"
           get(path)
         end
 
-        #https://auth0.com/docs/apiv2#!/stats/get_daily
+        # Gets the daily stats for a particular period.
+        # @see https://auth0.com/docs/api/v2#!/Stats/get_daily
+        # @param from [string]  The first day of the period (inclusive) in YYYYMMDD format.
+        # @param to [string] The last day of the period (inclusive) in YYYYMMDD format.
+        #
+        # @return [json] Returns the daily stats.
         def daily_stats(from, to)
-          path = "/api/v2/stats/daily"
+          path = "#{stats_path}/daily"
           request_params = {
             from: from,
             to: to
           }
           get(path, request_params)
         end
+
+        private
+
+        # Stats API path
+        def stats_path
+          @stats_path ||= '/api/v2/stats'
+        end
       end
     end
   end

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

@@ -0,0 +1,39 @@
+module Auth0
+  module Api
+    module V2
+      # Methods to use the Tenants endpoints
+      module Tenants
+        attr_reader :tenant_path
+
+        # Gets tenants settings.
+        # @see https://auth0.com/docs/api/v2#!/Tenants/get_settings
+        # @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 tenants settings.
+        def get_tenant_settings(fields: nil, include_fields: true)
+          request_params = {
+            fields: fields,
+            include_fields: include_fields
+          }
+          get(tenant_path, request_params)
+        end
+
+        # Updates tenants settings.
+        # @see https://auth0.com/docs/api/v2#!/Tenants/patch_settings
+        # @param body [hash] The Hash body used to define the tenants settings's properties.
+        # @return [json] Returns updated tenants settings.
+        def update_tenant_settings(body)
+          fail Auth0::InvalidParameter, 'Must supply a valid body to update tenant settings' if body.to_s.empty?
+          patch(tenant_path, body)
+        end
+
+        private
+
+        # Tenants settings API path
+        def tenant_path
+          @tenant_path ||= '/api/v2/tenants/settings'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+module Auth0
+  module Api
+    module V2
+      # Methods to use the tickets endpoints
+      module Tickets
+        attr_reader :tickets_path
+
+        # Create an email verification ticket
+        # @see https://auth0.com/docs/api/v2#!/Tickets/post_email_verification
+        # @param user_id [string] The user_id of for which the ticket is to be created
+        # @param result_url [string] The user will be redirected to this endpoint once the ticket is used
+        # @return [json] Returns ticket url
+        def post_email_verification(user_id, result_url: nil)
+          if user_id.to_s.empty?
+            fail Auth0::InvalidParameter, 'Must supply a valid user id to post an email verification'
+          end
+          path = "#{tickets_path}/email-verification"
+          request_params = {
+            user_id: user_id,
+            result_url: result_url
+          }
+          post(path, request_params)
+        end
+
+        # Create a password change ticket
+        # @see https://auth0.com/docs/api/v2#!/Tickets/post_password_change
+        # @param new_password [string] The password to set for the user once the ticket is used
+        # @param user_id [string] The user_id of for which the ticket is to be created
+        # @param result_url [string] The user will be redirected to this endpoint once the ticket is used
+        # @param connection_id [string] The connection that provides the identity for which the password is to be
+        # changed. If sending this parameter, the email is also required and the user_id is invalid
+        # @param email [string] The user's email
+        # @return [json] Returns ticket url
+        def post_password_change(new_password, user_id: nil, result_url: nil, connection_id: nil, email: nil)
+          if new_password.to_s.empty?
+            fail Auth0::InvalidParameter, 'Must supply a valid new password to post a password-change'
+          end
+          path = "#{tickets_path}/password-change"
+          request_params = {
+            user_id: user_id,
+            result_url: result_url,
+            new_password: new_password,
+            connection_id: connection_id,
+            email: email
+          }
+          post(path, request_params)
+        end
+
+        private
+
+        # Tickets API path
+        def tickets_path
+          @tickets_path ||= '/api/v2/tickets'
+        end
+      end
+    end
+  end
+end