react-redux-django-auth 1.1.0 → 1.2.0

package/README.md

@@ -0,0 +1,605 @@
+# React-Redux Authentication Hooks
+
+This package provides a suite of custom React hooks and a Redux Provider to streamline authentication in your application. By integrating with Redux, it offers a predictable state management solution for handling user authentication status, data, and errors.
+
+### Installation
+
+To get started, you'll need to install the package and its dependencies.
+
+```
+npm install react-redux-django-auth react-redux redux axios
+```
+
+or using yarn
+
+```
+yarn add react-redux-django-auth react-redux redux axios
+```
+
+# How to Use
+
+The core of this package is the AuthProvider component. This component wraps your entire application, making the Redux store available to all child components. This is a crucial step for the authentication hooks to function correctly.
+
+## Wrap Your Application
+
+The first step is to wrap your main App component with the AuthProvider. This is typically done in your entry file, such as `index.tsx` or `index.js`.
+
+```JavaScript
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { BrowserRouter } from 'react-router-dom';
+import App from './App';
+import AuthProvider from 'react-redux-django-auth'; // Add this import line
+
+const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
+
+root.render(
+<React.StrictMode>
+    <BrowserRouter>
+        <AuthProvider>
+            <App />
+        </AuthProvider>
+    </BrowserRouter>
+</React.StrictMode>
+);
+```
+
+By doing this, any component within your application can now access the authentication state and dispatch actions using the custom hooks provided by this package.
+
+## Using the Hooks
+
+Once the AuthProvider is in place, you can use any of the custom hooks (like useFacebookAuth, useGoogleAuth, etc.) in your components. These hooks handle the logic for authentication, state management, and error handling, making your components cleaner and easier to maintain. For example, a login component might use the useFacebookAuth hook to initiate the login process.
+
+### Login Hook Usage
+
+The `useLogin` hook is a custom hook designed to manage the state and logic for a login form, integrating directly with your Redux store for authentication. It handles form data, loading states, and dispatches login actions.
+
+1. Import the Hook and Set Up Initial State
+
+   First, import the useLogin hook into your component. You'll need to define an object for your initial form state, which should match the expected fields for your login form (e.g., email, password), as required in your django backend.
+
+   ```JavaScript
+   import useLogin from "react-redux-django-auth";
+
+   const initialFormData = {
+       email: "",
+       password: "",
+   };
+   ```
+
+2. Call the Hook in Your Component
+
+   Call the useLogin hook inside your functional component, passing the initialFormData and your API URL as arguments. The hook will return an object containing everything you need to manage your login form.
+
+   ```JavaScript
+   const apiURL = process.env.REACT_APP_API_URL; //Setup REACT_APP_API_URL in .env
+
+   const LogIn = () => {
+   const initialFormData = {
+       email: "",
+       password: "",
+   };
+
+   const { error, formData, isStatus200, loading, onChange, onSubmit } =
+       useLogin(initialFormData, apiURL);
+
+   // ... rest of your component logic
+   };
+   ```
+
+3. Connect the Returned Values to Your Form
+
+   Now, use the values returned from the hook to manage your form's state and behavior.
+
+   - `formData:` Binds the input values to the form state.
+
+   - `onChange:` Updates the form state as the user types.
+
+   - `onSubmit:` Handles the form submission, dispatches the login action, and manages the loading state.
+
+   - `loading:` A boolean value to disable the submit button during a network request.
+
+   - `error:` Displays any authentication errors returned from the Redux state.
+
+   - `isStatus200:` If the `status` is `200`, perform actions like navigation to a new page
+
+   ```jsx
+   <form className="row g-3" onSubmit={(e) => onSubmit(e)}>
+     {/* Email Input */}
+     <input
+       type="email"
+       name="email"
+       onChange={(e) => onChange(e)}
+       value={formData.email}
+       required
+     />
+
+     {/* Password Input */}
+     <input
+       type="password"
+       name="password"
+       onChange={(e) => onChange(e)}
+       value={formData.password}
+       required
+     />
+
+     {/* Submit Button */}
+     <button type="submit" disabled={loading}>
+       {loading ? "Logging In..." : "Log In"}
+     </button>
+
+     {/* Display Error Message */}
+     {error && <div className="text-danger">{error}</div>}
+   </form>
+   ```
+
+### Signup Hook Usage
+
+The `useSignup` hook is a custom hook designed to manage the state and logic for a user registration form. It integrates with your Redux store to handle form data, loading states, and dispatches sign-up actions.
+
+1. Import the Hook and Set Up Initial State
+
+   First, import the `useSignup` hook into your component. You'll need to define an object for your initial form state, which should match the expected fields for your sign-up form (e.g., email, password, etc.).
+
+   ```JavaScript
+   import useSignup from "react-redux-django-auth";
+
+   const initialFormData = {
+        // Add other fields as needed
+    email: "",
+    password: "",
+    re_password: "",
+   };
+   ```
+
+2. Call the Hook in Your Component
+   Call the useSignup hook inside your functional component, passing the initialFormData and your API URL as arguments. The hook will return an object containing everything you need to manage your sign-up form.
+
+   ```JavaScript
+   const apiURL = process.env.REACT_APP_API_URL;
+
+   const Signup = () => {
+    const initialFormData = {
+        // Add other fields as needed
+        email: "",
+        password: "",
+        re_password: "",
+    };
+
+    const { error, formData, isStatus201, loading, onChange, onSubmit } =
+    useSignup(initialFormData, apiURL);
+
+    // ... rest of your component logic
+   };
+   ```
+
+3. Connect the Returned Values to Your Form
+
+   Use the values returned from the hook to manage your form's state and behavior.
+
+   - `formData:` Binds the input values to the form state.
+
+   - `onChange:` Updates the form state as the user types.
+
+   - `onSubmit:` Handles the form submission, dispatches the sign-up action, and manages the loading state.
+
+   - `loading:` A boolean value to disable the submit button during a network request.
+
+   - `error:` Displays any authentication errors returned from the Redux state.
+
+   ```jsx
+   <form className="row g-3" onSubmit={(e) => onSubmit(e)}>
+     {/* Email Input */}
+     <input
+       type="email"
+       name="email"
+       onChange={(e) => onChange(e)}
+       value={formData.email}
+       required
+     />
+     // Add other form data
+     {/* Submit Button */}
+     <button type="submit" disabled={loading}>
+       {loading ? "Signing Up..." : "Sign Up"}
+     </button>
+     {/* Display Error Message */}
+     {error && <div className="text-danger">{error}</div>}
+   </form>
+   ```
+
+### `useActivate` Hook Usage
+
+The `useActivate` hook is a custom hook designed to handle the user account activation process. It leverages Redux to dispatch the necessary `verify` action, manages the loading state during the API call, and provides feedback on the activation status and any errors.
+
+#### 1\. Import the Hook and Get Parameters
+
+First, import the `useActivate` hook into your component. Typically, account activation links contain `uid` and `token` parameters, which you can extract from the URL using `useParams` from `react-router-dom`.
+
+```javascript
+import useActivate from "react-redux-django-auth";
+import { useParams } from "react-router-dom";
+
+const ActivateAccount = () => {
+  const { uid, token } = useParams();
+  const apiURL = process.env.REACT_APP_API_URL;
+  // ...
+};
+```
+
+#### 2\. Call the Hook in Your Component
+
+Call the `useActivate` hook inside your functional component, passing the `uid`, `token`, and your API URL as arguments. The hook will return an object with the logic needed to manage the activation.
+
+```javascript
+const { error, loading, onSubmit, isStatus204 } = useActivate(
+  uid,
+  token,
+  apiURL
+);
+```
+
+#### 3\. Connect the Returned Values to Your UI
+
+Use the values returned from the hook to manage your component's state and behavior.
+
+- `onSubmit`: This function triggers the account activation process. You should connect it to a button's `onClick` event.
+- `loading`: A boolean value to disable the button and show a loading spinner while the API call is in progress.
+- `error`: Displays any activation errors returned from the Redux state.
+- `isStatus204`: A boolean that can be used to detect a successful activation (a `204 No Content` status is often used for successful, non-returning operations).
+
+<!-- end list -->
+
+```jsx
+<form onSubmit={onSubmit}>
+  {/* The button that triggers the activation */}
+  <button
+    type="submit"
+    onClick={onSubmit}
+    disabled={loading}
+    className={loading ? "btn btn-primary disabled" : "btn btn-primary"}
+  >
+    {loading && <LoaderIcon />}
+    Click here to Verify your Account
+  </button>
+
+  {/* Display Error Message */}
+  {error && <div className="text-danger">{error}</div>}
+</form>
+```
+
+### `useResetPassword` Hook
+
+The `useResetPassword` hook is designed to manage the state and logic for a password reset request. It provides a simple way to handle the email input, loading state, and the form submission process, dispatching a Redux action to request the password reset.
+
+#### 1\. Call the Hook in Your Component
+
+Call the `useResetPassword` hook inside your functional component, passing your API URL as an argument. The hook will return an object with all the necessary state and functions to build a password reset form.
+
+```javascript
+import useResetPassword from "react-redux-django-auth";
+
+const ResetPasswordPage = () => {
+  const apiURL = process.env.REACT_APP_API_URL;
+  const { email, loading, handleChange, error, handleSubmit, isStatus204 } =
+    useResetPassword(apiURL);
+
+  // ... rest of your component logic
+};
+```
+
+#### 2\. Connect the Returned Values to Your Form
+
+Use the values returned from the hook to manage your form's state and behavior.
+
+- **`email`**: Binds the input value to the form state.
+- **`handleChange`**: Updates the form state as the user types. This function is specifically for a single email input field.
+- **`handleSubmit`**: Handles the form submission, dispatches the password reset action, and manages the loading state.
+- **`loading`**: A boolean value to disable the submit button during the API request.
+- **`error`**: Displays any authentication errors returned from the Redux state.
+- **`isStatus204`**: A boolean value that becomes `true` upon a successful submission, useful for showing success messages or redirecting the user.
+
+<!-- end list -->
+
+```jsx
+<form onSubmit={handleSubmit}>
+  {/* Email Input */}
+  <input
+    type="email"
+    name="email"
+    onChange={handleChange}
+    value={email}
+    required
+  />
+
+  {/* Submit Button */}
+  <button type="submit" disabled={loading}>
+    {loading ? "Sending..." : "Reset Password"}
+  </button>
+
+  {/* Display Error Message */}
+  {error && <div className="text-danger">{error}</div>}
+
+  {/* Success Message (optional) */}
+  {isStatus204 && (
+    <div className="text-success">Password reset email sent!</div>
+  )}
+</form>
+```
+
+### `usePasswordConfirm` Hook
+
+The `usePasswordConfirm` hook is designed to manage the state and logic for confirming a new password after a reset request. This hook handles the form data for the new password fields, manages the loading state, and dispatches the necessary Redux action to finalize the password change.
+
+#### 1\. Import the Hook and Set Up Initial State
+
+First, import the `usePasswordConfirm` hook into your component. The hook requires an object for your initial form state, which should include fields for the new password, a confirmation field, and the `uid` and `token` from the URL.
+
+```javascript
+import usePasswordConfirm from "react-redux-django-auth";
+import { useParams } from "react-router-dom";
+
+const ResetPasswordConfirm = () => {
+  const { uid, token } = useParams();
+  const apiURL = process.env.REACT_APP_API_URL;
+
+  const initialFormData = {
+    new_password: "",
+    re_new_password: "",
+    uid: uid,
+    token: token,
+  };
+
+  // ...
+};
+```
+
+#### 2\. Call the Hook in Your Component
+
+Call the `usePasswordConfirm` hook inside your functional component, passing the `initialFormData` and your API URL as arguments. The hook will return an object with all the necessary state and functions to build the form.
+
+```javascript
+const { loading, formData, error, onChange, onSubmit, isStatus204 } =
+  usePasswordConfirm(initialFormData, apiURL);
+```
+
+#### 3\. Connect the Returned Values to Your Form
+
+Use the values returned from the hook to manage your form's state and behavior.
+
+- **`formData`**: Binds the input values to the form state.
+- **`onChange`**: A function that updates the form state as the user types.
+- **`onSubmit`**: Handles the form submission, dispatches the password confirmation action, and manages the loading state.
+- **`loading`**: A boolean value to disable the submit button during a network request.
+- **`error`**: Displays any authentication errors returned from the Redux state.
+- **`isStatus204`**: A boolean that becomes `true` upon a successful submission, useful for showing success messages or redirecting the user.
+
+<!-- end list -->
+
+```jsx
+<form onSubmit={onSubmit}>
+  {/* New Password Input */}
+  <input
+    type="password"
+    name="new_password"
+    onChange={onChange}
+    value={formData.new_password}
+    required
+  />
+
+  {/* Confirm New Password Input */}
+  <input
+    type="password"
+    name="re_new_password"
+    onChange={onChange}
+    value={formData.re_new_password}
+    required
+  />
+
+  {/* Submit Button */}
+  <button type="submit" disabled={loading}>
+    {loading ? "Confirming..." : "Reset Password"}
+  </button>
+
+  {/* Display Error Message */}
+  {error && <div className="text-danger">{error}</div>}
+
+  {/* Success Message (optional) */}
+  {isStatus204 && <div className="text-success">Password has been reset!</div>}
+</form>
+```
+
+### `useLogout` Hook
+
+The `useLogout` hook is a straightforward custom hook designed to handle user logout. Its sole purpose is to dispatch the Redux action that clears the user's authentication state, making it a clean and reusable way to handle logouts across your application.
+
+#### 1\. Import the Hook
+
+First, import the `useLogout` hook into the component where you need to provide a logout function, such as a navigation bar or a user profile dropdown.
+
+```javascript
+import useLogout from "react-redux-django-auth";
+```
+
+#### 2\. Call the Hook in Your Component
+
+Call the `useLogout` hook inside your functional component. It doesn't take any arguments and returns a single function that you can attach to an event handler, such as a button's `onClick`.
+
+```javascript
+const UserProfile = () => {
+  const logout = useLogout();
+
+  // ...
+};
+```
+
+#### 3\. Attach the Function to a Logout Button
+
+Connect the `logout` function to a button or link that the user can click to sign out. When this function is called, it will dispatch the `logout` action to your Redux store, updating the application's authentication state.
+
+```jsx
+const UserProfile = () => {
+  const logout = useLogout();
+
+  return (
+    <div>
+      <p>Welcome, User!</p>
+      <button onClick={logout}>Log Out</button>
+    </div>
+  );
+};
+```
+
+This approach simplifies your components by abstracting the Redux dispatch logic into a dedicated hook, keeping your UI code clean and focused on rendering.
+
+### `useChangeAuthenticatedUserPassword` Hook
+
+The `useChangeAuthenticatedUserPassword` hook is a custom hook that simplifies the process of changing a user's password. It manages the form state for the current and new passwords, handles the loading state, and dispatches the necessary Redux action to update the password securely.
+
+#### 1\. Import the Hook and Set Up Initial State
+
+First, import the `useChangeAuthenticatedUserPassword` hook into your component. Define an object for your initial form state that includes fields for the current password, a new password, and a confirmation of the new password.
+
+```javascript
+import useChangeAuthenticatedUserPassword from "react-redux-django-auth";
+
+const initialFormData = {
+  current_password: "",
+  new_password: "",
+  confirm_new_password: "",
+};
+```
+
+#### 2\. Call the Hook in Your Component
+
+Call the `useChangeAuthenticatedUserPassword` hook inside your functional component, passing the `initialFormData` and your API URL as arguments. The hook will return an object with all the state and functions needed to build the password change form.
+
+```javascript
+const apiURL = process.env.REACT_APP_API_URL;
+
+const ChangePasswordForm = () => {
+  const { loading, formData, error, onChange, onSubmit, status } =
+    useChangeAuthenticatedUserPassword(initialFormData, apiURL);
+
+  // ... rest of your component logic
+};
+```
+
+#### 3\. Connect the Returned Values to Your Form
+
+Use the values returned from the hook to manage your form's state and behavior.
+
+- **`formData`**: Binds the input values to the form state.
+- **`onChange`**: A function that updates the form state as the user types.
+- **`onSubmit`**: Handles the form submission, including validation to ensure the new passwords match, and dispatches the password change action.
+- **`loading`**: A boolean value to disable the submit button while the API request is in progress.
+- **`error`**: Displays any validation errors (e.g., mismatched passwords) or authentication errors returned from the Redux state.
+
+<!-- end list -->
+
+```jsx
+<form onSubmit={onSubmit}>
+  {/* Current Password Input */}
+  <input
+    type="password"
+    name="current_password"
+    onChange={onChange}
+    value={formData.current_password}
+    required
+  />
+
+  {/* New Password Input */}
+  <input
+    type="password"
+    name="new_password"
+    onChange={onChange}
+    value={formData.new_password}
+    required
+  />
+
+  {/* Confirm New Password Input */}
+  <input
+    type="password"
+    name="confirm_new_password"
+    onChange={onChange}
+    value={formData.confirm_new_password}
+    required
+  />
+
+  {/* Submit Button */}
+  <button type="submit" disabled={loading}>
+    {loading ? "Changing..." : "Change Password"}
+  </button>
+
+  {/* Display Error Message */}
+  {error && <div className="text-danger">{error}</div>}
+</form>
+```
+
+### Documentation for `useAuthenticatedUser` Hook
+
+The `useAuthenticatedUser` hook is a central part of your authentication system, designed to manage the user's authentication status and profile data. It automatically checks authentication on page load or URL changes and provides functions to manually refresh the user's data or re-authenticate.
+
+#### 1\. Import the Hook and Call It in Your Component
+
+First, import the `useAuthenticatedUser` hook into a high-level component that needs access to the user's data, such as a layout component or a dashboard. You'll need to pass the `apiURL` and the current `location` (typically from `react-router-dom`) to the hook.
+
+```javascript
+import useAuthenticatedUser from "react-redux-django-auth";
+import { useLocation } from "react-router-dom";
+
+const DashboardLayout = () => {
+  const apiURL = process.env.REACT_APP_API_URL;
+  const location = useLocation();
+
+  const { isAuthenticated, currentUser, error, refreshUser } =
+    useAuthenticatedUser(apiURL, location);
+
+  // ...
+};
+```
+
+#### 2\. Access the Returned Values
+
+The hook returns a comprehensive object that you can use to conditionally render content, display user information, and handle errors.
+
+- **`isAuthenticated`**: A boolean (`true`, `false`, or `null` initially) that indicates if the user is authenticated.
+- **`currentUser`**: An object containing the user's profile data once it has been loaded.
+- **`error`**: Any authentication or profile-loading errors.
+- **`refreshUser`**: A function to manually re-fetch the user's profile data. This is useful for refreshing a profile after an update.
+- **`refreshAuth`**: A function to manually re-run the authentication check and then reload the user profile.
+- **`clearErrors`**: A function to manually clear any authentication-related errors from the Redux state.
+
+#### 3\. Example Usage
+
+You can use these values to build a dynamic and responsive UI. For instance, you can display a loading state, show different content for authenticated and unauthenticated users, and provide a way for the user to refresh their profile.
+
+```jsx
+const DashboardLayout = () => {
+  const apiURL = process.env.REACT_APP_API_URL;
+  const location = useLocation();
+
+  const { isAuthenticated, currentUser, error, refreshUser } =
+    useAuthenticatedUser(apiURL, location);
+
+  if (isAuthenticated === null) {
+    // Show a loading state while the initial check is happening
+    return <div>Checking authentication...</div>;
+  }
+
+  if (!isAuthenticated) {
+    // Redirect to login or show a "Please log in" message
+    return <Navigate to="/login" />;
+  }
+
+  // If isAuthenticated is true, currentUser will be available
+  return (
+    <div>
+      {error && <div className="text-danger">{error}</div>}
+      <h1>Welcome, {currentUser?.name}!</h1>
+      <button onClick={refreshUser}>Refresh Profile</button>
+      <nav>{/* Navigation links for authenticated users */}</nav>
+      {/* Rest of your dashboard content */}
+    </div>
+  );
+};
+```

package/dist/index.d.mts

@@ -34,9 +34,82 @@ interface SignupHookReturn {
 }
 declare const useSignup: (initialFields: any, apiUrl: string) => SignupHookReturn;
 
+interface AuthHookReturn {
+    error: any;
+    isAuthenticated: boolean | null;
+    currentUser: any;
+    clearErrors: () => void;
+    refreshUser: () => void;
+    refreshAuth: () => Promise<void>;
+}
+declare const useAuthicatedUser: (apiURL: string, location: any) => AuthHookReturn;
+
+interface ResetPasswordHookReturn {
+    email: string;
+    loading: boolean;
+    handleChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    status: any;
+    error: any;
+    handleSubmit: (e: React.FormEvent) => Promise<void>;
+    isStatus204: boolean;
+}
+declare const useResetPassword: (apiUrl: string) => ResetPasswordHookReturn;
+
+interface FormData$1 {
+    new_password?: string;
+    re_new_password?: string;
+    uid?: string;
+    token?: string;
+}
+interface PasswordConfirmHookReturn {
+    loading: boolean;
+    formData: FormData$1;
+    error: any;
+    onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    onSubmit: (e: React.FormEvent) => Promise<void>;
+    status: any;
+    isStatus204: boolean;
+}
+declare const usePasswordConfirm: (initialFields: FormData$1, apiUrl: string) => PasswordConfirmHookReturn;
+
+interface FormData {
+    current_password?: string;
+    new_password?: string;
+    confirm_new_password?: string;
+}
+interface ChangePasswordHookReturn {
+    loading: boolean;
+    formData: FormData;
+    error: string | null;
+    onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    onSubmit: (e: React.FormEvent) => Promise<void>;
+    status: any;
+}
+declare const useChangeAuthenticatedUserPassword: (initialFields: FormData, apiUrl: string) => ChangePasswordHookReturn;
+
+interface GoogleAuthHookReturn {
+    continueWithGoogle: () => Promise<void>;
+    authenticateWithGoogle: (state: string, code: string) => Promise<void>;
+    isAuthenticated: boolean | null;
+    error: any;
+    isStatus201: boolean;
+    loading: boolean;
+}
+declare const useGoogleAuth: (apiUrl: string) => GoogleAuthHookReturn;
+
+interface FacebookAuthHookReturn {
+    continueWithFacebook: () => Promise<void>;
+    authenticateWithFacebook: (state: string, code: string) => Promise<void>;
+    isAuthenticated: boolean | null;
+    error: any;
+    isStatus201: boolean;
+    loading: boolean;
+}
+declare const useFacebookAuth: (apiUrl: string) => FacebookAuthHookReturn;
+
 type AuthProviderProps = {
     children: React$1.ReactNode;
 };
 declare const AuthProvider: React$1.FC<AuthProviderProps>;
 
-export { AuthProvider, useActivate, useLogin, useLogout, useSignup };
+export { AuthProvider, useActivate, useAuthicatedUser, useChangeAuthenticatedUserPassword, useFacebookAuth, useGoogleAuth, useLogin, useLogout, usePasswordConfirm, useResetPassword, useSignup };