nextauthz 1.3.32 → 1.3.34

package/dist/index.js

@@ -92,8 +92,6 @@ function createAuthContext(option) {
           setAuth(true);
           if (storedUser) {
             const parsedUser = JSON.parse(storedUser);
-            console.log("parsedUser", parsedUser);
-            console.log("extractRole", extractRole(parsedUser));
             setUser(parsedUser);
             setRole(extractRole(parsedUser));
           }

package/dist/index.mjs

@@ -65,8 +65,6 @@ function createAuthContext(option) {
           setAuth(true);
           if (storedUser) {
             const parsedUser = JSON.parse(storedUser);
-            console.log("parsedUser", parsedUser);
-            console.log("extractRole", extractRole(parsedUser));
             setUser(parsedUser);
             setRole(extractRole(parsedUser));
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextauthz",
-  "version": "1.3.32",
+  "version": "1.3.34",
   "description": "",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/readme.md

@@ -2,106 +2,153 @@
 
 ## Overview
 
-This authentication system provides:
+  ** NextAuthZ provides:
 
-    ** Global auth state
+  ** Global auth state
 
-    ** Token persistence
+  ** Token persistence
 
-    ** Typed AuthProvider & useAuth
+  ** Typed AuthProvider & useAuth
 
-    ** Route protection
+  ** Route protection (AuthGuard)
 
-    ** Role-based access
+  ** Role-based protection (RoleGuard)
 
-    ** Configurable storage system
+  ** Configurable storage system
+
+  ** Configurable role extraction (rolePath)
+
+Works perfectly with Next.js App Router.
 
 ## Installation
 
 npm install nextauthz
 
+## Setup
 
-## AuthProvider & useAuth
+1️⃣ Create Your Auth Instance
 
-Purpose
-
-Wrap your application with AuthProvider to provide global auth state (user, loading, error) and helper functions (login, logout, setUser).
+Because NextAuthZ uses a factory pattern, you must create your own auth instance.
 
 ```bash
-import { createAppAuth } from 'nextauthz'
+// src/lib/auth.ts
+import { createAuthContext } from 'nextauthz'
+
+export const {
+  AuthProvider,
+  useAuth,
+} = createAuthContext({
+  storage: 'cookie',        // 'localStorage' | 'sessionStorage' | 'cookie'
+  tokenKey: 'access_token', // optional (default: 'access_token')
+  rolePath: 'account_type', // optional (default: 'role')
+})
+```
+
+## Available Options
 
-// Choose storage type
-const { AuthProvider, useAuth } = createAppAuth('cookie', 'access_token')
+| Option     | Type                                             | Default          | Description                           |
+| ---------- | ------------------------------------------------ | ---------------- | ------------------------------------- |
+| `storage`  | `'localStorage' \| 'sessionStorage' \| 'cookie'` | `'cookie'`       | Where tokens are stored               |
+| `tokenKey` | `string`                                         | `'access_token'` | Key used for primary token            |
+| `rolePath` | `string`                                         | `'role'`         | Path to extract role from user object |
 
 
-// Options: 'localStorage' | 'sessionStorage' | 'cookie'
-// Defaults to 'cookie' if no storage is passed
 
-function App({ children }: { children: React.ReactNode }) {
+
+## 2️⃣ Wrap Your App
+
+Wrap your application with AuthProvider to provide global auth state (user, loading, error) and helper functions (login, logout, setUser).
+
+```bash
+// app/layout.tsx
+
+import { AuthProvider } from '@/lib/auth'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
   return <AuthProvider>{children}</AuthProvider>
 }
-
-export default App
 ```
 
-## Hook: useAuth
+## useAuth Hook
 
 ```bash 
-import { useAuth } from 'nextauthz'
-
-const { user, role, login, logout, setUser, isAuthenticated, isAuthChecked } = useAuth()
+import { useAuth } from '@/lib/auth'
+
+const {
+  user,
+  role,
+  isAuthenticated,
+  isAuthChecked,
+  login,
+  logout,
+  setUser,
+} = useAuth()
 ```
 
 Available Properties
 
-| Name              | Type                                 | Description                                                   |
-| ----------------- | ------------------------------------ | ------------------------------------------------------------- |
-| `user`            | `User \| null`                       | Current authenticated user                                    |
-| `role`            | `string \| null`                     | User role                                                     |
-| `isAuthenticated` | `boolean`                            | True if the user is logged in                                 |
-| `isAuthChecked`   | `boolean`                            | True if auth state has finished restoring from storage/token  |
-| `login`           | `(tokens, userData?, role?) => void` | Logs in a user, saves tokens, and optionally sets user + role |
-| `logout`          | `() => void`                         | Clears auth tokens and resets state                           |
-| `setUser`         | `(user: User \| null) => void`       | Update user state manually                                    |
+| Name              | Type                                 | Description                              |
+| ----------------- | ------------------------------------ | ---------------------------------------- |
+| `user`            | `User \| null`                       | Current authenticated user               |
+| `role`            | `string \| null`                     | Extracted user role                      |
+| `isAuthenticated` | `boolean`                            | True if logged in                        |
+| `isAuthChecked`   | `boolean`                            | True when auth hydration is complete     |
+| `login`           | `(tokens, userData?, role?) => void` | Save tokens + optionally set user + role |
+| `logout`          | `() => void`                         | Clears tokens and resets auth            |
+| `setUser`         | `(user \| null) => void`             | Manually update user                     |
 
-
-Example: Logging in
+Example: Logging In
 
 ```bash 
-const handleLogin = () => {
+const { login } = useAuth()
+
+const handleLogin = async () => {
   const tokens = {
     access_token: 'abc123',
     refresh_token: 'xyz789',
   }
 
   const user = {
-    id: 1,
+    id: '1',
     name: 'John',
-    role: 'admin',
+    account_type: 'admin',
   }
 
-  login(tokens, user, user.role)
+  login(tokens, user)
 }
+```
 
-const handleLogout = () => {
-    logout(); // clears token and user
-    router.replace('/authentication/login');
-};
+If rolePath: 'account_type' is configured, role is automatically extracted.
+
+You can also override it manually:
+
+``` bash
+login(tokens, user, 'admin')
+```
+## Logging Out
+
+```bash
+const { logout } = useAuth()
+
+const handleLogin = async () => {
+  logout()
+  router.replace('/authentication/login');
+}
 ```
 
 ## AuthGuard
 
 Purpose
 
-Protect routes/pages to ensure only authenticated users can access them.
+Protect pages so only authenticated users can access them.
 
 Props
 
-| Name         | Type        | Default  | Description                            |
-| ------------ | ----------- | -------- | -------------------------------------- |
-| `children`   | `ReactNode` | required | Components to render if authenticated  |
-| `redirectTo` | `string`    | `/login` | Page to redirect unauthenticated users |
-| `fallback`   | `ReactNode` | `null`   | Optional loading or fallback UI        |
+| Name         | Type        | Default  | Description                        |
+| ------------ | ----------- | -------- | ---------------------------------- |
+| `children`   | `ReactNode` | required | Content to render if authenticated |
+| `redirectTo` | `string`    | `/login` | Redirect if not authenticated      |
+| `fallback`   | `ReactNode` | `null`   | Optional loading UI                |
 
 ## Usage Example
 
@@ -118,36 +165,34 @@ function DashboardPage() {
 ```
 Behavior:
 
-    ** Redirects to /login if the user is not authenticated.
+    ** Waits for isAuthChecked
+    ** Redirects to redirectTo value if not authenticated
+    ** Renders children if authenticated
 
 
 ## RoleGuard
 
-Purpose
+Restrict access based on role.
 
-RoleGuard restricts access to certain pages or components based on a user’s role. It assumes authentication is already handled (e.g., via AuthGuard or useAuth) and only checks whether the user’s role is allowed to access the content.
+Props
 
-| Name           | Type        | Default         | Description                                                   |
-| -------------- | ----------- | --------------- | ------------------------------------------------------------- |
-| `children`     | `ReactNode` | required        | Components to render if the user role is allowed              |
-| `allowedRoles` | `string[]`  | required        | List of roles allowed to access this page                     |
-| `redirectTo`   | `string`    | `/unauthorized` | Redirect page for unauthorized roles                          |
-| `fallback`     | `ReactNode` | `null`          | Optional loading or fallback UI displayed while checking role |
+| Name           | Type        | Default         | Description                  |
+| -------------- | ----------- | --------------- | ---------------------------- |
+| `children`     | `ReactNode` | required        | Content to render            |
+| `allowedRoles` | `string[]`  | required        | Allowed roles                |
+| `redirectTo`   | `string`    | `/unauthorized` | Redirect if role not allowed |
+| `fallback`     | `ReactNode` | `null`          | Optional loading UI          |
 
 
 Usage Example
 
 ```bash
-import RoleGuard from 'nextauthz'
-import { useAuth } from 'nextauthz'
-
-function AdminPage() {
-  const { user } = useAuth()
+import { RoleGuard } from 'nextauthz'
 
+export default function AdminPage() {
   return (
-    <RoleGuard allowedRoles={['admin']} fallback={<p>Checking permissions...</p>}>
+    <RoleGuard allowedRoles={['admin']} fallback={<p>Checking role...</p>}>
       <h1>Admin Dashboard</h1>
-      <p>Welcome, {user?.name}</p>
     </RoleGuard>
   )
 }
@@ -155,19 +200,52 @@ function AdminPage() {
 
 Behavior:
 
-    ** RoleGuard will show the fallback UI while the authentication state is loading (isAuthChecked is false).
-    ** 
+    ** Waits for isAuthChecked
+    ** Redirects if role not in allowedRoles
+    ** Blocks rendering if unauthorized
 
 
 ## Storage Options
 
 You can configure token storage:
 
-| Storage Type     | Description                     |
-| ---------------- | ------------------------------- |
-| `localStorage`   | Persists until manually cleared |
-| `sessionStorage` | Clears on tab close             |
-| `cookie`         | Cookie-based storage (default)  |
+| Storage Type     | Behavior               |
+| ---------------- | ---------------------- |
+| `localStorage`   | Persists until cleared |
+| `sessionStorage` | Clears on tab close    |
+| `cookie`         | Cookie-based (default) |
+
+## Role Path Examples
+Given this user:
+
+```bash 
+{
+  id: "1",
+  email: "user@email.com",
+  account_type: "artist"
+}
+```
+
+Use:
+
+```bash
+rolePath: 'account_type'
+```
+
+Nested example:
+```bash
+{
+  profile: {
+    role: 'admin'
+  }
+}
+```
+
+Use:
+
+```bash
+rolePath: 'profile.role'
+```
 
 
 ## Why NextAuthZ?
@@ -184,4 +262,8 @@ You can configure token storage:
 
     ** Lightweight
 
-    ** No opinionated backend
+    ** No opinionated backend
+
+    ** Backend agnostic
+
+    ** Factory-based (multiple auth instances supported)

package/src/AuthProvider.tsx

@@ -75,8 +75,6 @@ export function createAuthContext<UserType extends User = User>(option?: {
 
           if (storedUser) {
             const parsedUser = JSON.parse(storedUser) as UserType
-            console.log('parsedUser', parsedUser);
-            console.log('extractRole', extractRole(parsedUser));
             setUser(parsedUser)
             setRole(extractRole(parsedUser))
           }