strapi-plugin-keycloak-realm-users 1.0.0

package/admin/src/hooks/useKeycloakUsers.js

@@ -0,0 +1,477 @@
+/**
+ * @fileoverview React hook for managing Keycloak users within a realm.
+ * Provides comprehensive CRUD operations, password management, and bulk operations.
+ * @module admin/hooks/useKeycloakUsers
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import { useFetchClient, useNotification } from '@strapi/strapi/admin';
+import { API_BASE_PATH } from '../constants';
+
+/**
+ * @typedef {Object} KeycloakUser
+ * @property {string} id - Unique user identifier
+ * @property {string} username - Username
+ * @property {string} [email] - Email address
+ * @property {string} [firstName] - First name
+ * @property {string} [lastName] - Last name
+ * @property {boolean} enabled - Account enabled status
+ * @property {boolean} emailVerified - Email verification status
+ * @property {number} createdTimestamp - Account creation timestamp
+ */
+
+/**
+ * @typedef {Object} Pagination
+ * @property {number} page - Current page number (1-indexed)
+ * @property {number} pageSize - Items per page
+ * @property {number} total - Total items
+ * @property {number} pageCount - Total pages
+ */
+
+/**
+ * @typedef {Object} FetchUsersParams
+ * @property {string} [search=''] - Search query (matches username, email, name)
+ * @property {number} [page=1] - Page number
+ * @property {number} [pageSize=25] - Items per page
+ */
+
+/**
+ * @typedef {Object} BulkImportResult
+ * @property {Object[]} success - Successfully created users
+ * @property {Object[]} failed - Failed creations with error messages
+ */
+
+/**
+ * @typedef {Object} UseKeycloakUsersReturn
+ * @property {KeycloakUser[]} users - Array of users
+ * @property {boolean} isLoading - Loading state
+ * @property {Pagination} pagination - Pagination metadata
+ * @property {Function} fetchUsers - Fetch users with search/pagination
+ * @property {Function} getUser - Get single user by ID
+ * @property {Function} createUser - Create new user
+ * @property {Function} updateUser - Update user attributes
+ * @property {Function} deleteUser - Permanently delete user
+ * @property {Function} resetPassword - Set user password
+ * @property {Function} enableUser - Enable user account
+ * @property {Function} disableUser - Disable user account
+ * @property {Function} sendVerificationEmail - Send email verification link
+ * @property {Function} sendResetPasswordEmail - Send password reset email
+ * @property {Function} bulkImport - Import multiple users
+ * @property {Function} exportUsers - Export all users
+ */
+
+/**
+ * Hook for managing Keycloak users within a specific realm.
+ * Provides comprehensive user management including CRUD operations,
+ * password management, account status control, and bulk operations.
+ *
+ * @param {string} realmId - Realm document ID
+ * @returns {UseKeycloakUsersReturn} User management functions and state
+ *
+ * @example
+ * function UsersPage({ realmId }) {
+ *   const {
+ *     users,
+ *     isLoading,
+ *     pagination,
+ *     fetchUsers,
+ *     createUser,
+ *     deleteUser,
+ *   } = useKeycloakUsers(realmId);
+ *
+ *   return (
+ *     <UserTable
+ *       users={users}
+ *       loading={isLoading}
+ *       pagination={pagination}
+ *       onSearch={(search) => fetchUsers({ search })}
+ *       onPageChange={(page) => fetchUsers({ page })}
+ *       onDelete={(user) => deleteUser(user.id)}
+ *     />
+ *   );
+ * }
+ */
+export const useKeycloakUsers = (realmId) => {
+  const client = useFetchClient();
+  const { toggleNotification } = useNotification();
+
+  const [users, setUsers] = useState([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [pagination, setPagination] = useState({
+    page: 1,
+    pageSize: 25,
+    total: 0,
+    pageCount: 0,
+  });
+
+  /**
+   * Fetches users with optional search and pagination.
+   *
+   * @param {FetchUsersParams} [params={}] - Query parameters
+   * @returns {Promise<void>}
+   */
+  const fetchUsers = useCallback(
+    async ({ search = '', page = 1, pageSize = 25 } = {}) => {
+      if (!realmId) return;
+
+      setIsLoading(true);
+      try {
+        const { data } = await client.get(`${API_BASE_PATH}/realms/${realmId}/users`, {
+          params: { search, page, pageSize },
+        });
+        setUsers(data.data?.users || []);
+        setPagination(data.data?.pagination || { page: 1, pageSize: 25, total: 0, pageCount: 0 });
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to fetch users',
+        });
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [realmId, client, toggleNotification]
+  );
+
+  /**
+   * Fetches a single user by their Keycloak ID.
+   *
+   * @param {string} userId - Keycloak user ID
+   * @returns {Promise<KeycloakUser>} User details
+   * @throws {Error} If fetch fails
+   */
+  const getUser = useCallback(
+    async (userId) => {
+      try {
+        const { data } = await client.get(`${API_BASE_PATH}/realms/${realmId}/users/${userId}`);
+        return data.data;
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to fetch user',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification]
+  );
+
+  /**
+   * Creates a new user in Keycloak.
+   * Automatically refreshes the user list on success.
+   *
+   * @param {Object} userData - User data
+   * @param {string} userData.username - Required username
+   * @param {string} [userData.email] - Email address
+   * @param {string} [userData.firstName] - First name
+   * @param {string} [userData.lastName] - Last name
+   * @param {boolean} [userData.enabled=true] - Account enabled status
+   * @returns {Promise<KeycloakUser>} Created user
+   * @throws {Error} If creation fails
+   */
+  const createUser = useCallback(
+    async (userData) => {
+      try {
+        const { data } = await client.post(`${API_BASE_PATH}/realms/${realmId}/users`, {
+          data: userData,
+        });
+        toggleNotification({
+          type: 'success',
+          message: 'User created successfully',
+        });
+        await fetchUsers();
+        return data.data;
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to create user',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification, fetchUsers]
+  );
+
+  /**
+   * Updates an existing user's attributes.
+   * Automatically refreshes the user list on success.
+   *
+   * @param {string} userId - Keycloak user ID
+   * @param {Object} userData - Fields to update
+   * @returns {Promise<KeycloakUser>} Updated user
+   * @throws {Error} If update fails
+   */
+  const updateUser = useCallback(
+    async (userId, userData) => {
+      try {
+        const { data } = await client.put(`${API_BASE_PATH}/realms/${realmId}/users/${userId}`, {
+          data: userData,
+        });
+        toggleNotification({
+          type: 'success',
+          message: 'User updated successfully',
+        });
+        await fetchUsers();
+        return data.data;
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to update user',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification, fetchUsers]
+  );
+
+  /**
+   * Permanently deletes a user from Keycloak.
+   * Automatically refreshes the user list on success.
+   *
+   * @param {string} userId - Keycloak user ID
+   * @returns {Promise<void>}
+   * @throws {Error} If deletion fails
+   */
+  const deleteUser = useCallback(
+    async (userId) => {
+      try {
+        await client.del(`${API_BASE_PATH}/realms/${realmId}/users/${userId}`);
+        toggleNotification({
+          type: 'success',
+          message: 'User deleted successfully',
+        });
+        await fetchUsers();
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to delete user',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification, fetchUsers]
+  );
+
+  /**
+   * Sets a new password for a user.
+   *
+   * @param {string} userId - Keycloak user ID
+   * @param {string} password - New password
+   * @param {boolean} [temporary=true] - If true, user must change password on next login
+   * @returns {Promise<void>}
+   * @throws {Error} If password reset fails
+   */
+  const resetPassword = useCallback(
+    async (userId, password, temporary = true) => {
+      try {
+        await client.post(`${API_BASE_PATH}/realms/${realmId}/users/${userId}/reset-password`, {
+          data: { password, temporary },
+        });
+        toggleNotification({
+          type: 'success',
+          message: 'Password reset successfully',
+        });
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to reset password',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification]
+  );
+
+  /**
+   * Enables a user account.
+   * Automatically refreshes the user list on success.
+   *
+   * @param {string} userId - Keycloak user ID
+   * @returns {Promise<void>}
+   * @throws {Error} If enable fails
+   */
+  const enableUser = useCallback(
+    async (userId) => {
+      try {
+        await client.post(`${API_BASE_PATH}/realms/${realmId}/users/${userId}/enable`);
+        toggleNotification({
+          type: 'success',
+          message: 'User enabled successfully',
+        });
+        await fetchUsers();
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to enable user',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification, fetchUsers]
+  );
+
+  /**
+   * Disables a user account.
+   * Automatically refreshes the user list on success.
+   *
+   * @param {string} userId - Keycloak user ID
+   * @returns {Promise<void>}
+   * @throws {Error} If disable fails
+   */
+  const disableUser = useCallback(
+    async (userId) => {
+      try {
+        await client.post(`${API_BASE_PATH}/realms/${realmId}/users/${userId}/disable`);
+        toggleNotification({
+          type: 'success',
+          message: 'User disabled successfully',
+        });
+        await fetchUsers();
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to disable user',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification, fetchUsers]
+  );
+
+  /**
+   * Sends an email verification link to the user.
+   *
+   * @param {string} userId - Keycloak user ID
+   * @returns {Promise<void>}
+   * @throws {Error} If email send fails
+   */
+  const sendVerificationEmail = useCallback(
+    async (userId) => {
+      try {
+        await client.post(`${API_BASE_PATH}/realms/${realmId}/users/${userId}/send-verify-email`);
+        toggleNotification({
+          type: 'success',
+          message: 'Verification email sent',
+        });
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to send verification email',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification]
+  );
+
+  /**
+   * Sends a password reset email to the user.
+   *
+   * @param {string} userId - Keycloak user ID
+   * @returns {Promise<void>}
+   * @throws {Error} If email send fails
+   */
+  const sendResetPasswordEmail = useCallback(
+    async (userId) => {
+      try {
+        await client.post(`${API_BASE_PATH}/realms/${realmId}/users/${userId}/send-reset-password-email`);
+        toggleNotification({
+          type: 'success',
+          message: 'Password reset email sent',
+        });
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to send reset email',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification]
+  );
+
+  /**
+   * Bulk imports multiple users.
+   * Automatically refreshes the user list on completion.
+   *
+   * @param {Object[]} usersData - Array of user data objects
+   * @returns {Promise<BulkImportResult>} Import results with success/failed arrays
+   * @throws {Error} If import fails entirely
+   */
+  const bulkImport = useCallback(
+    async (usersData) => {
+      try {
+        const { data } = await client.post(`${API_BASE_PATH}/realms/${realmId}/users/import`, {
+          data: { users: usersData },
+        });
+        const result = data.data;
+        toggleNotification({
+          type: result.failed.length > 0 ? 'warning' : 'success',
+          message: `Imported ${result.success.length} users. ${result.failed.length} failed.`,
+        });
+        await fetchUsers();
+        return result;
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to import users',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification, fetchUsers]
+  );
+
+  /**
+   * Exports all users from the realm.
+   *
+   * @param {string} [format='json'] - Export format ('json' or 'csv')
+   * @returns {Promise<KeycloakUser[]|string>} Users array or CSV string
+   * @throws {Error} If export fails
+   */
+  const exportUsers = useCallback(
+    async (format = 'json') => {
+      try {
+        const { data } = await client.get(`${API_BASE_PATH}/realms/${realmId}/users/export`, {
+          params: { format },
+        });
+        return format === 'csv' ? data : data.data;
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to export users',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification]
+  );
+
+  // Fetch users when realmId changes
+  useEffect(() => {
+    if (realmId) {
+      fetchUsers();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [realmId]);
+
+  return {
+    users,
+    isLoading,
+    pagination,
+    fetchUsers,
+    getUser,
+    createUser,
+    updateUser,
+    deleteUser,
+    resetPassword,
+    enableUser,
+    disableUser,
+    sendVerificationEmail,
+    sendResetPasswordEmail,
+    bulkImport,
+    exportUsers,
+  };
+};
+
+export default useKeycloakUsers;