react-auth-service 0.0.1

package/README.md

@@ -0,0 +1,252 @@
+# Auth UI
+
+Reusable React **authentication UI library** with JWT handling, Axios interceptors, and routing helpers.
+
+> ⚠️ **Routing and navigation are owned by the consumer app**. This library provides UI, auth state, and API handling — not app routes.
+
+---
+
+## Why this package?
+
+Most apps repeat the same authentication logic:
+
+* Login & signup UI
+* JWT storage and refresh handling
+* Protecting routes
+* Attaching tokens to API calls
+
+**Auth UI** centralizes this logic into a reusable package so consumer apps can focus on business features.
+
+---
+
+## Features
+
+* 🔐 Login & Signup UI (`AuthForm`)
+* 👤 User profile UI (`UserProfile`)
+* 🧠 Central auth state via `AuthProvider`
+* 🛡️ Public & Protected route guards
+* 🔄 Axios interceptor with automatic token refresh
+* 🚫 Global session-expired handling
+
+---
+
+## Installation
+
+```bash
+npm install auth-ui
+```
+
+---
+
+## Required setup (important)
+
+### 1️⃣ Wrap your app with `AuthProvider` and `BrowserRouter`
+
+```tsx
+import { BrowserRouter } from 'react-router-dom';
+import { AuthProvider } from 'auth-ui';
+
+<BrowserRouter>
+  <AuthProvider>
+    <App />
+  </AuthProvider>
+</BrowserRouter>
+```
+
+> `BrowserRouter` **must be declared once** in the consumer app.
+
+---
+
+## Routing helpers
+
+This package does **not** define routes. Instead, it provides helpers you can compose with your routes.
+
+### PublicRoute
+
+Used for pages like **Login / Signup**.
+
+* Accessible only when user is **not authenticated**
+* Redirects authenticated users
+
+```tsx
+<Route
+  path="/"
+  element={
+    <PublicRoute>
+      <AuthForm onLoginSuccess={login} />
+    </PublicRoute>
+  }
+/>
+```
+
+### ProtectedRoute
+
+Used for **private pages**.
+
+* Blocks unauthenticated access
+* Redirects to login page
+
+```tsx
+<Route
+  path="/profile"
+  element={
+    <ProtectedRoute>
+      <UserProfile onLogout={logout} />
+    </ProtectedRoute>
+  }
+/>
+```
+
+---
+
+## Auth flow (how it works)
+
+### Login
+
+1. User submits login form
+2. Login API returns `accessToken`
+3. Token is stored in memory
+4. `AuthContext` updates auth state
+5. Consumer app handles navigation
+
+```ts
+setAccessToken(token);
+localStorage.setItem('isLoggedIn', 'true');
+```
+
+---
+
+### Signup
+
+1. User submits signup form
+2. Password is validated on client
+3. Registration API is called
+4. User is redirected to login mode
+
+---
+
+## Axios interceptor (core logic)
+
+This package exports a **preconfigured `axiosInstance`**.
+
+### What it does
+
+* Attaches `Authorization: Bearer <token>` automatically
+* Skips auth headers for login & signup APIs
+* Refreshes token automatically on expiry
+* Queues failed requests during refresh
+* Logs out user if refresh fails
+
+### Usage in consumer app
+
+```ts
+import { axiosInstance } from 'auth-ui';
+
+axiosInstance.get('/api/orders');
+```
+
+You **must use `axiosInstance`** instead of raw Axios to get auth benefits.
+
+---
+
+## Session expiration handling
+
+If refresh token fails:
+
+* User is logged out
+* Session-expired flag is stored
+* App redirects to login page
+
+On next load, `AuthForm` detects this and shows a session-expired message.
+
+---
+
+## Auth state management
+
+Auth state is managed via `AuthContext`.
+
+```ts
+const { isAuthenticated, login, logout } = useAuth();
+```
+
+* State is persisted using `localStorage`
+* Token is cleared on logout
+* Context ensures route guards stay in sync
+
+---
+
+## UserProfile component
+
+* Fetches user details on mount
+* Uses `axiosInstance` internally
+* Calls logout API on logout
+* Delegates navigation to consumer
+
+```tsx
+<UserProfile onLogout={logout} />
+```
+
+---
+
+## Consumer responsibilities
+
+The consumer app **must**:
+
+* Own routing and navigation
+* Provide backend APIs
+* Configure endpoints
+* Wrap app with `AuthProvider`
+* Use provided `axiosInstance`
+
+This library **does not**:
+
+* Create routes
+* Handle databases
+* Manage backend authentication
+
+---
+
+## Backend expectations
+
+Your backend should provide:
+
+* `POST /login` → returns `accessToken`
+* `POST /register`
+* `POST /refresh-token` (cookie-based)
+* `GET /user-details`
+* `POST /logout`
+
+JWT-based authentication is assumed.
+
+---
+
+## Common mistakes
+
+❌ Importing Axios directly instead of `axiosInstance`
+❌ Wrapping `BrowserRouter` multiple times
+❌ Using `useAuth` outside `AuthProvider`
+❌ Expecting this package to control routing
+
+---
+
+## Summary
+
+**Auth UI** provides:
+
+* UI components
+* Auth state management
+* Secure API handling
+
+You control:
+
+* Routing
+* Navigation
+* Backend
+
+This separation keeps your app flexible, secure, and scalable.
+
+---
+
+## License
+
+MIT