Add missing User endpoints for Management API

src/API/Management/GenericResource.php

@@ -106,6 +106,7 @@ protected function checkInvalidPermissions(array $permissions)
         }
 
         foreach ($permissions as $permission) {
+
             if (empty( $permission['permission_name'] )) {
                 throw new InvalidPermissionsArrayException();
             }

src/API/Management/Users.php

@@ -2,6 +2,9 @@
 
 namespace Auth0\SDK\API\Management;
 
+use Auth0\SDK\Exception\EmptyOrInvalidParameterException;
+use Auth0\SDK\Exception\InvalidPermissionsArrayException;
+
 /**
  * Class Users.
  * Handles requests to the Users endpoint of the v2 Management API.
@@ -77,19 +80,19 @@ public function create(array $data)
             throw new \Exception('Missing required "connection" field.');
         }
 
+        // A phone number is required for sms connections.
         if ('sms' === $data['connection'] && empty($data['phone_number'])) {
-            // "phone_number" field is required for an sms connection.
             throw new \Exception('Missing required "phone_number" field for sms connection.');
-        } else if ('sms' !== $data['connection']) {
-            // "email" field is required for email and DB connections.
-            if (empty($data['email'])) {
-                throw new \Exception('Missing required "email" field.');
-            }
+        }
 
-            // Passwords are required for DB connections.
-            if ('email' !== $data['connection'] && empty($data['password'])) {
-                throw new \Exception('Missing required "password" field for "'.$data['connection'].'" connection.');
-            }
+        // An email is required for email and DB connections.
+        if ('sms' !== $data['connection'] && empty($data['email'])) {
+            throw new \Exception('Missing required "email" field.');
+        }
+
+        // A password is required for DB connections.
+        if (! in_array( $data['connection'], [ 'email', 'sms' ] ) && empty($data['password'])) {
+            throw new \Exception('Missing required "password" field for "'.$data['connection'].'" connection.');
         }
 
         return $this->apiClient->method('post')
@@ -123,8 +126,6 @@ public function create(array $data)
      */
     public function getAll(array $params = [], $fields = null, $include_fields = null, $page = null, $per_page = null)
     {
-        $params = is_array($params) ? $params : [];
-
         // Fields to include/exclude.
         if (! isset($params['fields']) && null !== $fields) {
             $params['fields'] = $fields;
@@ -140,14 +141,7 @@ public function getAll(array $params = [], $fields = null, $include_fields = nul
             }
         }
 
-        // Keep existing pagination params if passed (backwards-compat), override with non-null function param if not.
-        if (! isset($params['page']) && null !== $page) {
-            $params['page'] = abs((int) $page);
-        }
-
-        if (! isset($params['per_page']) && null !== $per_page) {
-            $params['per_page'] = abs((int) $per_page);
-        }
+        $params = $this->normalizePagination( $params, $page, $per_page );
 
         return $this->apiClient->method('get')
             ->addPath('users')
@@ -233,6 +227,8 @@ public function unlinkAccount($user_id, $provider, $identity_id)
      * @return mixed|string
      *
      * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Users/delete_multifactor_by_provider
      */
     public function deleteMultifactorProvider($user_id, $mfa_provider)
     {
@@ -242,6 +238,285 @@ public function deleteMultifactorProvider($user_id, $mfa_provider)
             ->call();
     }
 
+    /**
+     * Get all roles assigned to a specific user.
+     * Required scopes:
+     *      - "read:users"
+     *      - "read:roles"
+     *
+     * @param string $user_id User ID to get roles for.
+     * @param array  $params  Additional listing params like page, per_page, and include_totals.
+     *
+     * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
+     *
+     * @return mixed
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Users/get_user_roles
+     */
+    public function getRoles($user_id, array $params = [])
+    {
+        $this->checkEmptyOrInvalidString($user_id, 'user_id');
+
+        $params = $this->normalizePagination( $params );
+        $params = $this->normalizeIncludeTotals( $params );
+
+        return $this->apiClient->method('get')
+            ->addPath('users', $user_id)
+            ->addPathVariable('roles')
+            ->withDictParams($params)
+            ->call();
+    }
+
+    /**
+     * Remove one or more roles from a specific user.
+     * Required scope: "update:users"
+     *
+     * @param string $user_id User ID to remove roles from.
+     * @param array  $roles   Array of permissions to remove.
+     *
+     * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
+     * @throws EmptyOrInvalidParameterException Thrown if the roles parameter is empty.
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
+     *
+     * @return mixed
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Users/delete_user_roles
+     */
+    public function removeRoles($user_id, array $roles)
+    {
+        $this->checkEmptyOrInvalidString($user_id, 'user_id');
+
+        if (empty($roles)) {
+            throw new EmptyOrInvalidParameterException('roles');
+        }
+
+        $data = [ 'roles' => $roles ];
+
+        return $this->apiClient->method('delete')
+            ->addPath('users', $user_id)
+            ->addPathVariable('roles')
+            ->withBody(json_encode($data))
+            ->call();
+    }
+
+    /**
+     * Add one or more roles to a specific user.
+     * Required scopes:
+     *      - "update:users"
+     *      - "read:roles"
+     *
+     * @param string $user_id User ID to add roles to.
+     * @param array  $roles   Array of roles to add.
+     *
+     * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
+     * @throws EmptyOrInvalidParameterException Thrown if the roles parameter is empty.
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
+     *
+     * @return mixed
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Users/post_user_roles
+     */
+    public function addRoles($user_id, array $roles)
+    {
+        $this->checkEmptyOrInvalidString($user_id, 'user_id');
+
+        if (empty($roles)) {
+            throw new EmptyOrInvalidParameterException('roles');
+        }
+
+        $data = [ 'roles' => $roles ];
+
+        return $this->apiClient->method('post')
+            ->addPath('users', $user_id)
+            ->addPathVariable('roles')
+            ->withBody(json_encode($data))
+            ->call();
+    }
+
+    /**
+     * Get all Guardian enrollments for a specific user.
+     * Required scope: "read:users"
+     *
+     * @param string $user_id User ID to get enrollments for.
+     *
+     * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
+     *
+     * @return mixed
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Users/get_enrollments
+     */
+    public function getEnrollments($user_id)
+    {
+        $this->checkEmptyOrInvalidString($user_id, 'user_id');
+
+        return $this->apiClient->method('get')
+            ->addPath('users', $user_id)
+            ->addPathVariable('enrollments')
+            ->call();
+    }
+
+    /**
+     * Get all permissions for a specific user.
+     * Required scope: "read:users"
+     *
+     * @param string $user_id User ID to get permissions for.
+     * @param array  $params  Additional listing params like page, per_page, and include_totals.
+     *
+     * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
+     *
+     * @return mixed
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Users/get_permissions
+     */
+    public function getPermissions($user_id, array $params = [])
+    {
+        $this->checkEmptyOrInvalidString($user_id, 'user_id');
+
+        $params = $this->normalizePagination( $params );
+        $params = $this->normalizeIncludeTotals( $params );
+
+        return $this->apiClient->method('get')
+            ->addPath('users', $user_id)
+            ->addPathVariable('permissions')
+            ->withDictParams($params)
+            ->call();
+    }
+
+    /**
+     * Remove one or more permissions from a specific user.
+     * Required scope: "update:users"
+     *
+     * @param string $user_id     User ID to remove permissions from.
+     * @param array  $permissions Array of permissions to remove.
+     *
+     * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
+     * @throws InvalidPermissionsArrayException Thrown if the permissions parameter is malformed.
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
+     *
+     * @return mixed
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Users/delete_permissions
+     */
+    public function removePermissions($user_id, array $permissions)
+    {
+        $this->checkEmptyOrInvalidString($user_id, 'user_id');
+        $this->checkInvalidPermissions( $permissions );
+
+        $data = [ 'permissions' => $permissions ];
+
+        return $this->apiClient->method('delete')
+            ->addPath('users', $user_id)
+            ->addPathVariable('permissions')
+            ->withBody(json_encode($data))
+            ->call();
+    }
+
+    /**
+     * Add one or more permissions to a specific user.
+     * Required scope: "update:users"
+     *
+     * @param string $user_id     User ID to add permissions to.
+     * @param array  $permissions Array of permissions to add.
+     *
+     * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
+     * @throws InvalidPermissionsArrayException Thrown if the permissions parameter is malformed.
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
+     *
+     * @return mixed
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Users/post_permissions
+     */
+    public function addPermissions($user_id, array $permissions)
+    {
+        $this->checkEmptyOrInvalidString($user_id, 'user_id');
+        $this->checkInvalidPermissions( $permissions );
+
+        $data = [ 'permissions' => $permissions ];
+
+        return $this->apiClient->method('post')
+            ->addPath('users', $user_id)
+            ->addPathVariable('permissions')
+            ->withBody(json_encode($data))
+            ->call();
+    }
+
+    /**
+     * Get log entries for a specific user.
+     * Required scope: "read:logs"
+     *
+     * @param string $user_id User ID to get logs entries for.
+     * @param array  $params  Additional listing params like page, per_page, sort, and include_totals.
+     *
+     * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
+     *
+     * @return mixed
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Users/get_logs_by_user
+     */
+    public function getLogs($user_id, array $params = [])
+    {
+        $this->checkEmptyOrInvalidString($user_id, 'user_id');
+
+        $params = $this->normalizePagination( $params );
+        $params = $this->normalizeIncludeTotals( $params );
+
+        return $this->apiClient->method('get')
+            ->addPath('users', $user_id)
+            ->addPathVariable('logs')
+            ->withDictParams($params)
+            ->call();
+    }
+
+    /**
+     * Removes the current Guardian recovery code and generates and returns a new one.
+     * Required scope: "update:users"
+     *
+     * @param string $user_id User ID to remove and generate recovery codes for.
+     *
+     * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
+     *
+     * @return mixed
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Users/post_recovery_code_regeneration
+     */
+    public function generateRecoveryCode($user_id)
+    {
+        $this->checkEmptyOrInvalidString($user_id, 'user_id');
+
+        return $this->apiClient->method('post')
+            ->addPath('users', $user_id)
+            ->addPathVariable('recovery-code-regeneration')
+            ->call();
+    }
+
+    /**
+     * Invalidates all remembered browsers for all authentication factors for a specific user.
+     * Required scope: "update:users"
+     *
+     * @param string $user_id User ID to invalidate browsers for.
+     *
+     * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
+     *
+     * @return mixed
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Users/post_invalidate_remember_browser
+     */
+    public function invalidateBrowsers($user_id)
+    {
+        $this->checkEmptyOrInvalidString($user_id, 'user_id');
+
+        return $this->apiClient->method('post')
+            ->addPath('users', $user_id)
+            ->addPathVariable('multifactor/actions/invalidate-remember-browser')
+            ->call();
+    }
+
     /*
      * Deprecated
      */