@rqdhw3n/react-auth-flow 1.0.3 → 1.0.5

package/README.md

@@ -1,569 +1,261 @@
-# @rqdhw3n/react-auth-flow
-
-A production-ready, TypeScript-first authentication flow package for React applications. Provides a complete solution for handling user authentication with minimal configuration while maintaining flexibility.
-
-## Features
-
-- 🔐 **Secure by default**: HttpOnly cookie JWT support
-- ⚡ **Zero dependencies**: Uses native fetch API
-- 🎣 **Custom hooks**: `useAuth()` hook for accessing auth state
-- 🔄 **Auto-refresh**: Automatic session refresh capability
-- 🎨 **Unstyled components**: Ready-to-use forms with full customization
-- 🛣️ **Protected routes**: React Router v6 compatible route protection
-- 📦 **TypeScript support**: Full type safety throughout
-- 🔌 **Customizable**: Custom headers, endpoints, and request adapters
-- 🚀 **SSR-friendly**: Works with server-side rendering when configured properly
-
-## Installation
-
-```bash
-npm install @rqdhw3n/react-auth-flow react react-dom react-router-dom
-```
-
-or with yarn:
-
-```bash
-yarn add @rqdhw3n/react-auth-flow react react-dom react-router-dom
-```
-
-## Quick Setup
-
-### 1. Wrap your app with AuthProvider
-
-```tsx
-import { AuthProvider } from '@rqdhw3n/react-auth-flow';
-
-function App() {
-  return (
-    <AuthProvider
-      baseURL="https://api.example.com"
-      autoRefresh={true}
-      refreshInterval={5 * 60 * 1000} // 5 minutes
-    >
-      {/* Your app components */}
-    </AuthProvider>
-  );
-}
-```
-
-### 2. Use the useAuth hook
-
-```tsx
-import { useAuth } from '@rqdhw3n/react-auth-flow';
-
-function Header() {
-  const { user, isAuthenticated, logout } = useAuth();
-
-  if (!isAuthenticated) {
-    return <span>Please log in</span>;
-  }
-
-  return (
-    <div>
-      <p>Welcome, {user?.name}</p>
-      <button onClick={logout}>Logout</button>
-    </div>
-  );
-}
-```
-
-## Usage Examples
-
-### LoginForm Component
-
-```tsx
-import { LoginForm } from '@rqdhw3n/react-auth-flow';
-import { useNavigate } from 'react-router-dom';
-
-function LoginPage() {
-  const navigate = useNavigate();
-
-  return (
-    <LoginForm
-      className="my-login-form"
-      labels={{
-        email: 'Email Address',
-        password: 'Password',
-        rememberMe: 'Keep me signed in',
-      }}
-      placeholders={{
-        email: 'name@example.com',
-        password: 'Enter your password',
-      }}
-      submitButtonText="Sign In"
-      onSuccess={(user) => {
-        console.log('Logged in:', user);
-        navigate('/dashboard');
-      }}
-      onError={(error) => {
-        console.error('Login failed:', error);
-      }}
-    />
-  );
-}
-```
-
-### RegisterForm Component
-
-```tsx
-import { RegisterForm } from '@rqdhw3n/react-auth-flow';
-
-function SignUpPage() {
-  return (
-    <RegisterForm
-      submitButtonText="Create Account"
-      labels={{
-        name: 'Full Name',
-        email: 'Email Address',
-        password: 'Password',
-        confirmPassword: 'Confirm Password',
-      }}
-      onSuccess={() => {
-        // Navigate to email verification or login
-      }}
-      onError={(error) => {
-        alert(error.message);
-      }}
-    />
-  );
-}
-```
-
-### ForgotPasswordForm Component
-
-```tsx
-import { ForgotPasswordForm } from '@rqdhw3n/react-auth-flow';
-
-function ForgotPasswordPage() {
-  return (
-    <ForgotPasswordForm
-      submitButtonText="Send Recovery Email"
-      labels={{
-        email: 'Enter your email address',
-      }}
-      onSuccess={() => {
-        alert('Recovery email sent! Check your inbox.');
-      }}
-    />
-  );
-}
-```
-
-### ResetPasswordForm Component
-
-```tsx
-import { ResetPasswordForm } from '@rqdhw3n/react-auth-flow';
-import { useSearchParams } from 'react-router-dom';
-
-function ResetPasswordPage() {
-  const [searchParams] = useSearchParams();
-  const token = searchParams.get('token') || '';
-
-  return (
-    <ResetPasswordForm
-      token={token}
-      submitButtonText="Update Password"
-      onSuccess={() => {
-        alert('Password updated successfully!');
-        // Navigate to login
-      }}
-    />
-  );
-}
-```
-
-### VerifyEmailForm Component
-
-```tsx
-import { VerifyEmailForm } from '@rqdhw3n/react-auth-flow';
-import { useSearchParams } from 'react-router-dom';
-
-function VerifyEmailPage() {
-  const [searchParams] = useSearchParams();
-  const token = searchParams.get('token') || '';
-  const email = searchParams.get('email') || '';
-
-  return (
-    <VerifyEmailForm
-      token={token}
-      email={email}
-      onSuccess={() => {
-        alert('Email verified!');
-      }}
-    />
-  );
-}
-```
-
-### ProtectedRoute Component
-
-```tsx
-import { ProtectedRoute } from '@rqdhw3n/react-auth-flow';
-import { Routes, Route } from 'react-router-dom';
-
-function App() {
-  return (
-    <Routes>
-      <Route path="/login" element={<LoginPage />} />
-      <Route
-        path="/dashboard"
-        element={
-          <ProtectedRoute redirectTo="/login">
-            <Dashboard />
-          </ProtectedRoute>
-        }
-      />
-      <Route
-        path="/admin"
-        element={
-          <ProtectedRoute 
-            roles={['admin']} 
-            redirectTo="/unauthorized"
-          >
-            <AdminPanel />
-          </ProtectedRoute>
-        }
-      />
-      <Route
-        path="/manage-users"
-        element={
-          <ProtectedRoute 
-            permissions={['users.manage', 'users.delete']}
-            redirectTo="/unauthorized"
-          >
-            <UserManagement />
-          </ProtectedRoute>
-        }
-      />
-    </Routes>
-  );
-}
-```
-
-### useAuth Hook
-
-```tsx
-import { useAuth } from '@rqdhw3n/react-auth-flow';
-
-function UserProfile() {
-  const {
-    user,
-    isAuthenticated,
-    isLoading,
-    error,
-    login,
-    logout,
-    refreshSession,
-    setUser,
-  } = useAuth();
-
-  const handleLogin = async () => {
-    try {
-      const user = await login({
-        email: 'user@example.com',
-        password: 'password',
-        rememberMe: true,
-      });
-      console.log('Logged in as:', user);
-    } catch (err) {
-      console.error('Login failed:', err);
-    }
-  };
-
-  const handleLogout = async () => {
-    await logout();
-    console.log('Logged out');
-  };
-
-  if (isLoading) {
-    return <div>Loading...</div>;
-  }
-
-  if (error) {
-    return <div>Error: {error.message}</div>;
-  }
-
-  if (!isAuthenticated) {
-    return <button onClick={handleLogin}>Login</button>;
-  }
-
-  return (
-    <div>
-      <h1>Hello, {user?.name}</h1>
-      <p>Email: {user?.email}</p>
-      <p>Roles: {user?.roles?.join(', ')}</p>
-      <button onClick={handleLogout}>Logout</button>
-      <button onClick={refreshSession}>Refresh Session</button>
-    </div>
-  );
-}
-```
-
-## API Endpoints Configuration
-
-The package expects your backend to provide the following endpoints by default:
-
-### Default Endpoints
-
-- `POST /auth/login` - Login with email and password
-- `POST /auth/register` - Register a new account
-- `POST /auth/logout` - Logout the user
-- `GET /auth/me` - Get current user information
-- `POST /auth/refresh` - Refresh authentication token
-- `POST /auth/forgot-password` - Request password reset
-- `POST /auth/reset-password` - Reset password with token
-- `POST /auth/verify-email` - Verify email with token
-
-### Customizing Endpoints
-
-```tsx
-import { AuthProvider } from '@rqdhw3n/react-auth-flow';
-
-<AuthProvider
-  baseURL="https://api.example.com"
-  endpoints={{
-    login: '/auth/signin',
-    register: '/auth/signup',
-    me: '/user/profile',
-    // ... other endpoints
-  }}
->
-  {/* Your app */}
-</AuthProvider>
-```
-
-## Expected API Response Formats
-
-### Login Response
-
-```json
-{
-  "user": {
-    "id": 1,
-    "name": "John Doe",
-    "email": "john@example.com",
-    "roles": ["admin"],
-    "permissions": ["users.manage", "users.delete"]
-  }
-}
-```
-
-### Current User (Me) Response
-
-```json
-{
-  "user": {
-    "id": 1,
-    "name": "John Doe",
-    "email": "john@example.com",
-    "roles": ["admin"],
-    "permissions": ["users.manage", "users.delete"]
-  }
-}
-```
-
-### Error Response
-
-```json
-{
-  "error": {
-    "code": "INVALID_CREDENTIALS",
-    "message": "Invalid email or password",
-    "statusCode": 401
-  }
-}
-```
-
-## HttpOnly Cookie JWT Authentication
-
-For enhanced security, configure your backend to use HttpOnly cookies:
-
-```tsx
-// Backend should set a cookie like:
-// Set-Cookie: jwt=token; HttpOnly; Secure; SameSite=Strict; Max-Age=3600
-
-// The package will automatically include cookies with requests
-// because credentials: "include" is set by default
-```
-
-## Custom Headers and Request Adapter
-
-```tsx
-import { createAuthClient } from '@rqdhw3n/react-auth-flow';
-
-// Create a custom client
-const authClient = createAuthClient({
-  baseURL: 'https://api.example.com',
-  headers: {
-    'X-API-Key': 'your-api-key',
-    'X-Client-Version': '1.0.0',
-  },
-  credentials: 'include', // for HttpOnly cookies
-  adapter: async (url, options) => {
-    // Custom request logic
-    console.log('Making request to:', url);
-    return fetch(url, options);
-  },
-});
-
-// Use in AuthProvider
-<AuthProvider
-  baseURL="https://api.example.com"
-  // ... other config
->
-  {/* Your app */}
-</AuthProvider>
-```
-
-## TypeScript Customization
-
-Extend types for your application:
-
-```tsx
-import { AuthUser, AuthContextValue } from '@rqdhw3n/react-auth-flow';
-
-// Extend the AuthUser type
-interface AppUser extends AuthUser {
-  id: number;
-  name: string;
-  email: string;
-  roles: string[];
-  permissions: string[];
-  company?: string;
-  department?: string;
-}
-
-// Use in your components
-import { useAuth } from '@rqdhw3n/react-auth-flow';
-
-function MyComponent() {
-  const { user } = useAuth();
-  const appUser = user as AppUser;
-
-  return <div>Working in {appUser.department}</div>;
-}
-```
-
-## Styling Components
-
-All form components use semantic class names for styling:
-
-```css
-.auth-form-group {
-  margin-bottom: 1rem;
-}
-
-.auth-form-label {
-  display: block;
-  margin-bottom: 0.5rem;
-  font-weight: 500;
-}
-
-.auth-form-input {
-  width: 100%;
-  padding: 0.5rem;
-  border: 1px solid #ccc;
-  border-radius: 4px;
-  font-size: 1rem;
-}
-
-.auth-form-input:disabled {
-  background-color: #f5f5f5;
-  cursor: not-allowed;
-}
-
-.auth-form-error {
-  color: #dc3545;
-  margin-top: 0.5rem;
-  font-size: 0.875rem;
-}
-
-.auth-form-button {
-  padding: 0.5rem 1rem;
-  border: none;
-  border-radius: 4px;
-  font-size: 1rem;
-  cursor: pointer;
-  width: 100%;
-}
-
-.auth-form-button-primary {
-  background-color: #007bff;
-  color: white;
-}
-
-.auth-form-button-primary:hover {
-  background-color: #0056b3;
-}
-
-.auth-form-button:disabled {
-  opacity: 0.5;
-  cursor: not-allowed;
-}
-
-.auth-form-checkbox {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-}
-
-.auth-form-checkbox .auth-form-label {
-  margin-bottom: 0;
-}
-
-.auth-form-success {
-  padding: 1rem;
-  background-color: #d4edda;
-  border: 1px solid #c3e6cb;
-  border-radius: 4px;
-  color: #155724;
-}
-
-.auth-form-success-message {
-  margin: 0;
-}
-
-.auth-loading {
-  text-align: center;
-  padding: 2rem;
-  font-size: 1rem;
-}
-
-.auth-forbidden {
-  padding: 2rem;
-  text-align: center;
-  color: #dc3545;
-}
-```
-
-## Error Handling
-
-The package normalizes all errors to a consistent format:
-
-```tsx
-import { useAuth, AuthError } from '@rqdhw3n/react-auth-flow';
-
-function MyComponent() {
-  const { error } = useAuth();
-
-  if (error) {
-    const authError: AuthError = error;
-    console.log({
-      code: authError.code, // e.g., "INVALID_CREDENTIALS"
-      message: authError.message,
-      statusCode: authError.statusCode, // e.g., 401
-      details: authError.details, // additional error info
-    });
-  }
-
-  return <div>Status: {error?.message}</div>;
-}
-```
-
-## License
-
-MIT
-
-## Support
-
-For issues and feature requests, please visit the [GitHub repository](https://github.com/rqdhw3n/react-auth-flow).
+# @rqdhw3n/react-auth-flow
+
+A TypeScript-first authentication flow package for React applications with built-in, production-ready auth form styling.
+
+## Features
+
+- Secure by default with cookie-based auth support
+- Zero UI framework dependency
+- Built-in stylesheet loaded automatically from the package entry
+- Ready-to-use `LoginForm`, `RegisterForm`, `ForgotPasswordForm`, `ResetPasswordForm`, and `VerifyEmailForm`
+- `AuthProvider` and `useAuth()` for auth state management
+- `ProtectedRoute` support for React Router
+- Customizable endpoints, headers, and request adapters
+- Override-friendly class name props for consumer styling
+
+## Installation
+
+```bash
+npm install @rqdhw3n/react-auth-flow react react-dom react-router-dom
+```
+
+No Tailwind, PostCSS, `tailwind.config.js`, or manual CSS import is required. Importing the package automatically loads the packaged auth stylesheet.
+
+## Quick Setup
+
+### Wrap your app with `AuthProvider`
+
+```tsx
+import { AuthProvider } from "@rqdhw3n/react-auth-flow";
+
+function App() {
+  return (
+    <AuthProvider
+      baseURL="https://api.example.com"
+      autoRefresh={true}
+      refreshInterval={5 * 60 * 1000}
+    >
+      {/* your app */}
+    </AuthProvider>
+  );
+}
+```
+
+### Use `useAuth()`
+
+```tsx
+import { useAuth } from "@rqdhw3n/react-auth-flow";
+
+function Header() {
+  const { user, isAuthenticated, logout } = useAuth();
+
+  if (!isAuthenticated) {
+    return <span>Please log in</span>;
+  }
+
+  return (
+    <div>
+      <p>Welcome, {user?.name}</p>
+      <button onClick={logout}>Logout</button>
+    </div>
+  );
+}
+```
+
+## Forms
+
+### Styled out of the box
+
+```tsx
+import { LoginForm } from "@rqdhw3n/react-auth-flow";
+
+function App() {
+  return <LoginForm />;
+}
+```
+
+### Login form
+
+```tsx
+import { LoginForm } from "@rqdhw3n/react-auth-flow";
+import { useNavigate } from "react-router-dom";
+
+function LoginPage() {
+  const navigate = useNavigate();
+
+  return (
+    <div
+      style={{
+        minHeight: "100vh",
+        display: "grid",
+        placeItems: "center",
+        padding: 24,
+        background: "#f4f7fb",
+      }}
+    >
+      <LoginForm
+        title="Welcome back"
+        subtitle="Sign in to continue"
+        submitButtonText="Sign In"
+        loadingText="Signing in..."
+        labels={{
+          email: "Email Address",
+          password: "Password",
+          rememberMe: "Keep me signed in",
+        }}
+        onSuccess={() => navigate("/dashboard")}
+      />
+    </div>
+  );
+}
+```
+
+### Register form
+
+```tsx
+import { RegisterForm } from "@rqdhw3n/react-auth-flow";
+
+function SignUpPage() {
+  return (
+    <RegisterForm
+      title="Create your account"
+      subtitle="Get started in seconds"
+      submitButtonText="Create Account"
+      loadingText="Creating account..."
+    />
+  );
+}
+```
+
+### Forgot password form
+
+```tsx
+import { ForgotPasswordForm } from "@rqdhw3n/react-auth-flow";
+
+function ForgotPasswordPage() {
+  return (
+    <ForgotPasswordForm
+      title="Reset your password"
+      subtitle="Enter your email to receive a reset link"
+    />
+  );
+}
+```
+
+### Reset password form
+
+```tsx
+import { ResetPasswordForm } from "@rqdhw3n/react-auth-flow";
+import { useSearchParams } from "react-router-dom";
+
+function ResetPasswordPage() {
+  const [searchParams] = useSearchParams();
+  const token = searchParams.get("token") || "";
+
+  return (
+    <ResetPasswordForm
+      token={token}
+      title="Create a new password"
+      subtitle="Use at least 8 characters"
+    />
+  );
+}
+```
+
+### Verify email form
+
+```tsx
+import { VerifyEmailForm } from "@rqdhw3n/react-auth-flow";
+import { useSearchParams } from "react-router-dom";
+
+function VerifyEmailPage() {
+  const [searchParams] = useSearchParams();
+
+  return (
+    <VerifyEmailForm
+      token={searchParams.get("token") || ""}
+      email={searchParams.get("email") || ""}
+      title="Verify your email"
+      subtitle="Enter the verification code you received"
+    />
+  );
+}
+```
+
+## Styling Overrides
+
+The package ships with default classes and also supports consumer overrides through props:
+
+- `className`
+- `formClassName`
+- `fieldClassName`
+- `labelClassName`
+- `inputClassName`
+- `buttonClassName`
+- `errorClassName`
+- `successClassName`
+- `titleClassName`
+- `subtitleClassName`
+
+Example:
+
+```tsx
+import { LoginForm } from "@rqdhw3n/react-auth-flow";
+
+function CustomLoginPage() {
+  return (
+    <LoginForm
+      className="my-auth-card"
+      formClassName="my-auth-form"
+      labelClassName="my-auth-label"
+      inputClassName="my-auth-input"
+      buttonClassName="my-auth-button"
+      errorClassName="my-auth-error"
+      successClassName="my-auth-success"
+    />
+  );
+}
+```
+
+Default packaged class names:
+
+- `.rq-auth-container`
+- `.rq-auth-form`
+- `.rq-auth-field`
+- `.rq-auth-label`
+- `.rq-auth-input`
+- `.rq-auth-button`
+- `.rq-auth-error`
+- `.rq-auth-success`
+- `.rq-auth-title`
+- `.rq-auth-subtitle`
+- `.rq-auth-checkbox`
+
+## Protected Routes
+
+```tsx
+import { ProtectedRoute } from "@rqdhw3n/react-auth-flow";
+import { Routes, Route } from "react-router-dom";
+
+function AppRoutes() {
+  return (
+    <Routes>
+      <Route path="/login" element={<LoginPage />} />
+      <Route
+        path="/dashboard"
+        element={
+          <ProtectedRoute redirectTo="/login">
+            <Dashboard />
+          </ProtectedRoute>
+        }
+      />
+    </Routes>
+  );
+}
+```
+
+## Notes
+
+- The package stylesheet is imported from `src/index.ts`, so consumers do not need `import "./styles.css"` in their apps.
+- Build output includes JavaScript bundles and an emitted CSS asset in `dist`.
+- The components are responsive by default and work on desktop and mobile without extra setup.