@rqdhw3n/react-auth-flow 1.0.0

package/README.md

@@ -0,0 +1,569 @@
+# @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).

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@rqdhw3n/react-auth-flow",
+  "version": "1.0.0",
+  "description": "A reusable authentication flow package for React applications",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.es.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.es.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext ts,tsx",
+    "test": "vitest",
+    "prepublish": "npm run build"
+  },
+  "keywords": [
+    "react",
+    "authentication",
+    "auth-flow",
+    "typescript",
+    "jwt",
+    "login",
+    "register"
+  ],
+  "author": "@rqdhw3n",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "react-router-dom": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-router-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@types/react-router-dom": "^5.3.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "eslint": "^8.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-router-dom": "^6.0.0",
+    "typescript": "^5.0.0",
+    "vite": "^4.0.0",
+    "vitest": "^0.34.0"
+  }
+}