@artatol-acp/auth-nextjs 0.3.8 → 0.4.0

package/README.md

@@ -2,11 +2,64 @@
 
 Next.js SDK for Artatol Cloud Platform Authentication with support for App Router, Server Actions, Middleware, and automatic token refresh.
 
+## Changelog
+
+### v0.4.0
+
+**Breaking Changes:**
+- `ACPAuthProvider` no longer requires `baseUrl` prop - it now uses local API routes
+- `initACPAuth()` no longer returns an `ACPAuthClient` instance
+
+**New Features:**
+- **New `handlers` export**: Pre-built API route handlers for auth operations
+  ```typescript
+  import { createAuthHandlers } from '@artatol-acp/auth-nextjs/handlers';
+  ```
+- **SSR-first architecture**: `ACPAuthProvider` now accepts `initialUser` prop for SSR hydration
+- **New `verify2FALogin()` server function**: Complete 2FA login flow on the server
+- **New `verify2FA()` client method**: Complete 2FA login from client components
+
+**Improvements:**
+- **httpOnly cookies**: All tokens are now stored in httpOnly cookies (XSS protection)
+- **Proper cookie handling**: `login()` now automatically sets both `access_token` and `refresh_token` cookies
+- **Server-side refresh**: `refreshAccessToken()` now properly forwards cookies to auth server
+- **Better error messages**: Clear error when `baseUrl` is missing
+- **Configurable cookies**: Cookie options (path, secure, sameSite) are now configurable
+
+**Migration Guide:**
+
+1. Create API route handlers:
+   ```typescript
+   // app/api/auth/[action]/route.ts
+   import { createAuthHandlers } from '@artatol-acp/auth-nextjs/handlers';
+
+   const { authHandler } = createAuthHandlers({
+     baseUrl: process.env.ACP_AUTH_URL!,
+   });
+
+   export const POST = authHandler;
+   ```
+
+2. Update `ACPAuthProvider`:
+   ```typescript
+   // Before
+   <ACPAuthProvider baseUrl={process.env.NEXT_PUBLIC_ACP_AUTH_URL}>
+
+   // After
+   <ACPAuthProvider initialUser={user}>
+   ```
+
+3. Handle 2FA in login:
+   ```typescript
+   const result = await login(email, password);
+   if (result.requiresTwoFactor) {
+     // Show 2FA form, then call verify2FA(tempToken, code)
+   }
+   ```
+
 ## Installation
 
 ```bash
-npm install @artatol-acp/auth-nextjs
-# or
 pnpm add @artatol-acp/auth-nextjs
 ```
 
@@ -14,67 +67,94 @@ pnpm add @artatol-acp/auth-nextjs
 
 Before using this SDK, you need to obtain from the ACP AUTH service:
 
-1. **API Key** (required) - Contact your system administrator
-2. **Base URL** (required) - The auth service URL (e.g., `https://sso.artatol.net`)
-3. **JWT Public Key** (optional) - Only needed for local JWT verification with `getUser()`. Download it from:
+1. **Base URL** (required) - The auth service URL (e.g., `https://sso.artatol.net`)
+2. **API Key** (optional) - Contact your system administrator if required
+3. **JWT Public Key** (required for `getUser()`) - For local JWT verification. Download it from:
    ```bash
    curl https://sso.artatol.net/public-key > public.pem
    ```
 
-   **Note:** Without the public key, you can still use all auth operations (login, register, logout, 2FA, password reset, etc.), but you must use the `me()` function instead of `getUser()` for user verification, which makes an API call to the auth service.
+## Quick Start
 
-## Setup
+The SDK uses **httpOnly cookies** for secure token storage. This means:
+- Tokens are NOT accessible from JavaScript (XSS protection)
+- All auth operations must go through your Next.js server
+- The SDK provides API route handlers to proxy requests to the auth server
 
-### 1. Initialize Server-side
+### 1. Create API Route Handlers
 
-Create `lib/auth.ts`:
+Create `app/api/auth/[action]/route.ts`:
 
 ```typescript
-import { initACPAuth } from '@artatol-acp/auth-nextjs/server';
-import { readFileSync } from 'fs';
+import { createAuthHandlers } from '@artatol-acp/auth-nextjs/handlers';
 
-const publicKey = readFileSync('./keys/public.pem', 'utf-8');
-
-export const auth = initACPAuth({
-  baseUrl: process.env.ACP_AUTH_URL || 'https://sso.artatol.com',
-  apiKey: process.env.ACP_AUTH_API_KEY!,
-  jwtPublicKey: publicKey,
+const { authHandler } = createAuthHandlers({
+  baseUrl: process.env.ACP_AUTH_URL!,
+  apiKey: process.env.ACP_AUTH_API_KEY,
 });
+
+export const POST = authHandler;
 ```
 
-### 2. Add Middleware (Optional)
+This creates the following endpoints:
+- `POST /api/auth/login` - Login
+- `POST /api/auth/logout` - Logout
+- `POST /api/auth/session` - Refresh session & get user
+- `POST /api/auth/register` - Register
+- `POST /api/auth/verify-2fa` - Complete 2FA login
+- `POST /api/auth/resend-verification` - Resend verification email
+- `POST /api/auth/forgot-password` - Request password reset
+- `POST /api/auth/reset-password` - Reset password
 
-Create `middleware.ts`:
+### 2. Initialize Server-side Auth
+
+Create `lib/auth.ts`:
 
 ```typescript
-import { createACPAuthMiddleware } from '@artatol-acp/auth-nextjs/middleware';
+import { initACPAuth } from '@artatol-acp/auth-nextjs/server';
 import { readFileSync } from 'fs';
 
 const publicKey = readFileSync('./keys/public.pem', 'utf-8');
 
-export const middleware = createACPAuthMiddleware({
+initACPAuth({
+  baseUrl: process.env.ACP_AUTH_URL!,
+  apiKey: process.env.ACP_AUTH_API_KEY,
   jwtPublicKey: publicKey,
-  publicPaths: ['/login', '/register', '/forgot-password'],
-  loginPath: '/login',
 });
 
-export const config = {
-  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
-};
+// Re-export server functions
+export {
+  getUser,
+  me,
+  login,
+  logout,
+  register,
+  verify2FALogin,
+  verifyEmail,
+  resendVerificationEmail,
+  forgotPassword,
+  resetPassword,
+  deleteAccount,
+  refreshAccessToken,
+} from '@artatol-acp/auth-nextjs/server';
 ```
 
-### 3. Add Client Provider (Optional)
+### 3. Add Client Provider
 
 In your root layout (`app/layout.tsx`):
 
 ```typescript
 import { ACPAuthProvider } from '@artatol-acp/auth-nextjs/client';
+import { getUser } from '@/lib/auth';
+
+export default async function RootLayout({ children }) {
+  // SSR: Get initial user on server
+  const user = await getUser();
 
-export default function RootLayout({ children }) {
   return (
     <html>
       <body>
-        <ACPAuthProvider baseUrl={process.env.NEXT_PUBLIC_ACP_AUTH_URL}>
+        <ACPAuthProvider initialUser={user}>
           {children}
         </ACPAuthProvider>
       </body>
@@ -85,14 +165,18 @@ export default function RootLayout({ children }) {
 
 ## Usage
 
-### Server Components
+### Server Components (SSR)
 
 ```typescript
-import { getUser } from '@artatol-acp/auth-nextjs/server';
+import { getUser, me } from '@/lib/auth';
 
 export default async function ProfilePage() {
+  // Fast local JWT verification (returns { id, email })
   const user = await getUser();
 
+  // Or fetch full user from API (returns { id, email, twoFactorEnabled })
+  const fullUser = await me();
+
   if (!user) {
     return <div>Not logged in</div>;
   }
@@ -110,7 +194,7 @@ export default async function ProfilePage() {
 ```typescript
 'use server';
 
-import { login, register, logout } from '@artatol-acp/auth-nextjs/server';
+import { login, register, logout, verify2FALogin } from '@/lib/auth';
 import { redirect } from 'next/navigation';
 
 export async function loginAction(formData: FormData) {
@@ -120,19 +204,22 @@ export async function loginAction(formData: FormData) {
   const result = await login(email, password);
 
   if ('requiresTwoFactor' in result) {
-    // Handle 2FA
     return { requires2FA: true, tempToken: result.tempToken };
   }
 
   redirect('/dashboard');
 }
 
+export async function verify2FAAction(tempToken: string, code: string) {
+  await verify2FALogin(tempToken, code);
+  redirect('/dashboard');
+}
+
 export async function registerAction(formData: FormData) {
   const email = formData.get('email') as string;
   const password = formData.get('password') as string;
 
   await register(email, password);
-  // User will receive verification email
   redirect('/check-email');
 }
 
@@ -148,29 +235,50 @@ export async function logoutAction() {
 'use client';
 
 import { useAuth } from '@artatol-acp/auth-nextjs/client';
+import { useState } from 'react';
 
 export function LoginForm() {
-  const { login, user, isLoading } = useAuth();
+  const { login, verify2FA, user, isLoading } = useAuth();
+  const [tempToken, setTempToken] = useState<string | null>(null);
 
-  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
+  const handleLogin = async (e: React.FormEvent<HTMLFormElement>) => {
     e.preventDefault();
     const formData = new FormData(e.currentTarget);
 
     try {
-      await login(
+      const result = await login(
         formData.get('email') as string,
         formData.get('password') as string
       );
+
+      if (result.requiresTwoFactor) {
+        setTempToken(result.tempToken!);
+      }
     } catch (error) {
       console.error('Login failed:', error);
     }
   };
 
+  const handle2FA = async (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const code = new FormData(e.currentTarget).get('code') as string;
+    await verify2FA(tempToken!, code);
+  };
+
   if (isLoading) return <div>Loading...</div>;
   if (user) return <div>Welcome {user.email}</div>;
 
+  if (tempToken) {
+    return (
+      <form onSubmit={handle2FA}>
+        <input name="code" placeholder="2FA Code" required />
+        <button type="submit">Verify</button>
+      </form>
+    );
+  }
+
   return (
-    <form onSubmit={handleSubmit}>
+    <form onSubmit={handleLogin}>
       <input name="email" type="email" required />
       <input name="password" type="password" required />
       <button type="submit">Login</button>
@@ -179,505 +287,177 @@ export function LoginForm() {
 }
 ```
 
-### API Routes
+## Middleware (Optional)
+
+Create `middleware.ts` for route protection:
 
 ```typescript
-import { ACPAuthClient } from '@artatol-acp/auth-nextjs/server';
+import { createACPAuthMiddleware } from '@artatol-acp/auth-nextjs/middleware';
+import { readFileSync } from 'fs';
 
-const client = new ACPAuthClient({
-  baseUrl: process.env.ACP_AUTH_URL!,
-  apiKey: process.env.ACP_AUTH_API_KEY!,
+const publicKey = readFileSync('./keys/public.pem', 'utf-8');
+
+export const middleware = createACPAuthMiddleware({
+  jwtPublicKey: publicKey,
+  publicPaths: ['/login', '/register', '/forgot-password'],
+  loginPath: '/login',
 });
 
-export async function POST(request: Request) {
-  const { email, password } = await request.json();
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
+};
+```
 
-  const result = await client.login({ email, password });
+## Environment Variables
 
-  return Response.json(result);
-}
+```env
+ACP_AUTH_URL=https://sso.artatol.net
+ACP_AUTH_API_KEY=your-api-key-here
 ```
 
-## Password Requirements
+## API Reference
 
-Passwords must meet the following requirements:
-- Minimum 10 characters
-- At least one lowercase letter (a-z)
-- At least one uppercase letter (A-Z)
-- At least one number (0-9)
+### Server Functions (`@artatol-acp/auth-nextjs/server`)
+
+| Function | Description |
+|----------|-------------|
+| `initACPAuth(options)` | Initialize auth configuration |
+| `getUser()` | Get user from JWT (local, fast) → `{ id, email }` |
+| `me()` | Get user from API (full data) → `{ id, email, twoFactorEnabled }` |
+| `login(email, password)` | Login user, sets httpOnly cookies |
+| `verify2FALogin(tempToken, code)` | Complete 2FA login |
+| `logout()` | Logout user, clears cookies |
+| `register(email, password)` | Register new user |
+| `verifyEmail(token)` | Verify email address |
+| `resendVerificationEmail(email)` | Resend verification email |
+| `forgotPassword(email)` | Request password reset |
+| `resetPassword(token, password)` | Reset password |
+| `deleteAccount(password, confirmation)` | Delete account |
+| `refreshAccessToken()` | Refresh access token |
+
+### Client Hook (`@artatol-acp/auth-nextjs/client`)
 
 ```typescript
-// Example validation on the client side
-function validatePassword(password: string): string[] {
-  const errors: string[] = [];
-
-  if (password.length < 10) {
-    errors.push('Password must be at least 10 characters');
-  }
-  if (!/[a-z]/.test(password)) {
-    errors.push('Password must contain at least one lowercase letter');
-  }
-  if (!/[A-Z]/.test(password)) {
-    errors.push('Password must contain at least one uppercase letter');
-  }
-  if (!/[0-9]/.test(password)) {
-    errors.push('Password must contain at least one number');
-  }
-
-  return errors;
-}
+const {
+  user,           // Current user or null
+  isLoading,      // True during initial load
+  login,          // (email, password) => Promise<{ requiresTwoFactor?, tempToken? }>
+  verify2FA,      // (tempToken, code) => Promise<void>
+  logout,         // () => Promise<void>
+  refresh,        // () => Promise<boolean>
+  resendVerification, // (email) => Promise<void>
+} = useAuth();
 ```
 
-## Email Verification
-
-After registration, users must verify their email address before they can log in. The auth service automatically sends a verification email upon registration.
-
-### Verification Flow
-
-1. User registers → receives verification email
-2. User clicks link in email → email is verified
-3. User can now log in
-
-### Server Actions
+### ACPAuthProvider Props
 
 ```typescript
-'use server';
-
-import { verifyEmail, resendVerificationEmail } from '@artatol-acp/auth-nextjs/server';
-import { redirect } from 'next/navigation';
-
-export async function verifyEmailAction(token: string) {
-  try {
-    await verifyEmail(token);
-    redirect('/login?verified=true');
-  } catch (error) {
-    redirect('/verification-error');
-  }
-}
-
-export async function resendVerificationAction(email: string) {
-  await resendVerificationEmail(email);
-  // Always succeeds to prevent email enumeration
-  return { message: 'If the email exists, a verification link has been sent' };
-}
+<ACPAuthProvider
+  apiBasePath="/api/auth"  // Optional, default: "/api/auth"
+  initialUser={user}       // Optional, SSR user data
+>
+  {children}
+</ACPAuthProvider>
 ```
 
-### Client Component Example
+### API Handlers (`@artatol-acp/auth-nextjs/handlers`)
 
 ```typescript
-'use client';
-
-import { useAuth } from '@artatol-acp/auth-nextjs/client';
+const handlers = createAuthHandlers({
+  baseUrl: string,
+  apiKey?: string,
+  cookies?: {
+    path?: string,      // Default: "/"
+    secure?: boolean,   // Default: NODE_ENV === "production"
+    sameSite?: 'strict' | 'lax' | 'none', // Default: "lax"
+  },
+});
 
-export function ResendVerificationButton({ email }: { email: string }) {
-  const { resendVerification } = useAuth();
-  const [sent, setSent] = useState(false);
+// Use combined handler
+export const POST = handlers.authHandler;
 
-  const handleResend = async () => {
-    await resendVerification(email);
-    setSent(true);
-  };
-
-  return (
-    <button onClick={handleResend} disabled={sent}>
-      {sent ? 'Email Sent' : 'Resend Verification Email'}
-    </button>
-  );
-}
+// Or use individual handlers
+export const POST = handlers.loginHandler;
 ```
 
-### Handling Unverified Users
-
-When an unverified user tries to log in, they will receive an error:
+## Error Handling
 
 ```typescript
-export async function loginAction(formData: FormData) {
-  const email = formData.get('email') as string;
-  const password = formData.get('password') as string;
+import { ACPAuthError } from '@artatol-acp/auth-nextjs/server';
 
-  try {
-    const result = await login(email, password);
-
-    if ('requiresTwoFactor' in result) {
-      return { requires2FA: true, tempToken: result.tempToken };
-    }
-
-    redirect('/dashboard');
-  } catch (error: any) {
-    if (error.message?.includes('Email not verified')) {
-      return { error: 'Please verify your email before logging in' };
+try {
+  await login(email, password);
+} catch (error) {
+  if (error instanceof ACPAuthError) {
+    console.error('Message:', error.message);
+    console.error('Status:', error.statusCode);
+    console.error('Code:', error.code);
+
+    if (error.isAuthError()) {
+      // 401 - Invalid credentials
+    } else if (error.isValidationError()) {
+      // 400 - Validation error
+    } else if (error.isNetworkError()) {
+      // Network/connection error
     }
-    throw error;
   }
 }
 ```
 
-## Environment Variables
-
-```env
-ACP_AUTH_URL=https://sso.artatol.com
-ACP_AUTH_API_KEY=your-api-key-here
-NEXT_PUBLIC_ACP_AUTH_URL=https://sso.artatol.com
-```
-
-## API Reference
-
-### Server Functions
-
-- `initACPAuth(options)` - Initialize the auth client
-- `getUser()` - Get current user from JWT (local verification, returns `{ id, email }`)
-- `me()` - Get current user from API (returns full `User` with `twoFactorEnabled`)
-- `verifyAccessToken(token)` - Verify and decode access token (returns `{ id, email }`)
-
-```typescript
-// getUser() returns JWTUser (fast, local)
-type JWTUser = {
-  id: string;
-  email: string;
-};
-
-// me() returns User (API call, complete data)
-type User = {
-  id: string;
-  email: string;
-  twoFactorEnabled: boolean;
-};
-```
-- `refreshAccessToken()` - Refresh access token using refresh token cookie
-- `login(email, password)` - Login user
-- `logout()` - Logout user
-- `register(email, password)` - Register new user (sends verification email)
-- `verifyEmail(token)` - Verify user's email address
-- `resendVerificationEmail(email)` - Resend verification email
-- `forgotPassword(email)` - Request password reset email
-- `resetPassword(token, newPassword)` - Reset password using token from email
-- `deleteAccount(password, confirmation)` - Delete authenticated user's account
-
-### Client Hooks
-
-- `useAuth()` - Access auth context (user, isLoading, login, logout, refresh)
+### Common Error Codes
 
-### Middleware
+| Status | Meaning |
+|--------|---------|
+| 400 | Validation error (bad input) |
+| 401 | Unauthorized (invalid credentials/token) |
+| 403 | Forbidden (email not verified, account locked) |
+| 429 | Too Many Requests (rate limited) |
 
-- `createACPAuthMiddleware(options)` - Create middleware for route protection
+## Password Requirements
 
-## 2FA (Two-Factor Authentication)
+- Minimum 10 characters
+- At least one lowercase letter (a-z)
+- At least one uppercase letter (A-Z)
+- At least one number (0-9)
 
-### Setup 2FA
+## 2FA Setup
 
 ```typescript
 'use server';
 
 import { ACPAuthClient } from '@artatol-acp/auth-nextjs/server';
+import { cookies } from 'next/headers';
 
 export async function setup2FAAction(password: string) {
+  const cookieStore = await cookies();
+  const accessToken = cookieStore.get('access_token')?.value;
+
   const client = new ACPAuthClient({
     baseUrl: process.env.ACP_AUTH_URL!,
-    apiKey: process.env.ACP_AUTH_API_KEY!,
+    apiKey: process.env.ACP_AUTH_API_KEY,
   });
 
-  const accessToken = // ... get from session/cookie
-
-  const { secret, qrCodeUrl, recoveryCodes } = await client.setup2FA(
+  const { qrCodeUrl, recoveryCodes } = await client.setup2FA(
     { password },
     accessToken
   );
 
   return { qrCodeUrl, recoveryCodes };
 }
-```
 
-### Verify 2FA Setup
+export async function verify2FASetupAction(code: string) {
+  const cookieStore = await cookies();
+  const accessToken = cookieStore.get('access_token')?.value;
 
-```typescript
-'use server';
-
-export async function verify2FAAction(code: string) {
   const client = new ACPAuthClient({
     baseUrl: process.env.ACP_AUTH_URL!,
-    apiKey: process.env.ACP_AUTH_API_KEY!,
+    apiKey: process.env.ACP_AUTH_API_KEY,
   });
 
-  const accessToken = // ... get from session/cookie
-
   await client.verify2FA({ code }, accessToken);
 }
 ```
 
-### Complete 2FA Login Flow
-
-```typescript
-'use server';
-
-import { login } from '@artatol-acp/auth-nextjs/server';
-
-export async function loginAction(email: string, password: string) {
-  const result = await login(email, password);
-
-  if ('requiresTwoFactor' in result) {
-    // User has 2FA enabled
-    return {
-      requires2FA: true,
-      tempToken: result.tempToken,
-    };
-  }
-
-  // Regular login successful
-  return { success: true };
-}
-
-export async function complete2FALogin(tempToken: string, code: string) {
-  const client = new ACPAuthClient({
-    baseUrl: process.env.ACP_AUTH_URL!,
-    apiKey: process.env.ACP_AUTH_API_KEY!,
-  });
-
-  const result = await client.verify2FALogin({ tempToken, code });
-  // Set cookies, etc.
-  return result;
-}
-```
-
-### Disable 2FA
-
-```typescript
-'use server';
-
-export async function disable2FAAction(password: string, code: string) {
-  const client = new ACPAuthClient({
-    baseUrl: process.env.ACP_AUTH_URL!,
-    apiKey: process.env.ACP_AUTH_API_KEY!,
-  });
-
-  const accessToken = // ... get from session/cookie
-
-  await client.disable2FA({ password, code }, accessToken);
-}
-```
-
-## Password Reset
-
-### Forgot Password
-
-Request a password reset email:
-
-```typescript
-'use server';
-
-import { forgotPassword } from '@artatol-acp/auth-nextjs/server';
-
-export async function forgotPasswordAction(formData: FormData) {
-  const email = formData.get('email') as string;
-
-  await forgotPassword(email);
-  // Always succeeds to prevent email enumeration
-  return { message: 'If the email exists, a reset link has been sent' };
-}
-```
-
-### Reset Password
-
-Reset password using the token from the email:
-
-```typescript
-'use server';
-
-import { resetPassword } from '@artatol-acp/auth-nextjs/server';
-import { redirect } from 'next/navigation';
-
-export async function resetPasswordAction(formData: FormData) {
-  const token = formData.get('token') as string;
-  const newPassword = formData.get('password') as string;
-
-  try {
-    await resetPassword(token, newPassword);
-    redirect('/login?reset=success');
-  } catch (error) {
-    return { error: 'Invalid or expired reset token' };
-  }
-}
-```
-
-### Client Component Example
-
-```typescript
-'use client';
-
-import { useState } from 'react';
-import { forgotPasswordAction } from './actions';
-
-export function ForgotPasswordForm() {
-  const [submitted, setSubmitted] = useState(false);
-
-  const handleSubmit = async (formData: FormData) => {
-    await forgotPasswordAction(formData);
-    setSubmitted(true);
-  };
-
-  if (submitted) {
-    return <p>Check your email for a password reset link.</p>;
-  }
-
-  return (
-    <form action={handleSubmit}>
-      <input name="email" type="email" placeholder="Email" required />
-      <button type="submit">Send Reset Link</button>
-    </form>
-  );
-}
-```
-
-## Delete Account
-
-Delete the authenticated user's account:
-
-```typescript
-'use server';
-
-import { deleteAccount } from '@artatol-acp/auth-nextjs/server';
-import { redirect } from 'next/navigation';
-
-export async function deleteAccountAction(formData: FormData) {
-  const password = formData.get('password') as string;
-  const confirmation = formData.get('confirmation') as string;
-
-  try {
-    await deleteAccount(password, confirmation);
-    redirect('/goodbye');
-  } catch (error) {
-    return { error: 'Failed to delete account. Check your password.' };
-  }
-}
-```
-
-**Note:** The `confirmation` parameter must be the string `"DELETE"` to confirm account deletion.
-
-## Health Check
-
-To check if the auth service is available:
-
-```typescript
-import { ACPAuthClient } from '@artatol-acp/auth-nextjs/server';
-
-const client = new ACPAuthClient({
-  baseUrl: process.env.ACP_AUTH_URL!,
-  apiKey: process.env.ACP_AUTH_API_KEY!,
-});
-
-const health = await client.health();
-console.log(health); // { status: 'ok', timestamp: '...' }
-```
-
-## Automatic Token Refresh
-
-The Next.js SDK includes automatic token refresh functionality on the client side via the `ACPAuthProvider`.
-
-### How It Works
-
-1. When you use `ACPAuthProvider`, the SDK automatically manages access tokens
-2. After successful login, a background interval starts
-3. **Every 4 minutes**, the token is automatically refreshed (tokens expire after 5 minutes)
-4. If refresh fails, the user is automatically logged out
-5. The interval stops when the user logs out or the component unmounts
-
-### Client-Side Usage
-
-```typescript
-'use client';
-
-import { ACPAuthProvider } from '@artatol-acp/auth-nextjs/client';
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        <ACPAuthProvider
-          baseUrl={process.env.NEXT_PUBLIC_ACP_AUTH_URL}
-        >
-          {children}
-        </ACPAuthProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-The `ACPAuthProvider` internally creates an `ACPAuthClient` with auto-refresh enabled:
-- `autoRefresh: true` (enabled by default)
-- `refreshThresholdSeconds: 60` (refreshes 60 seconds before token expires)
-
-### Manual Token Management
-
-If you're using the client directly without the provider:
-
-```typescript
-import { ACPAuthClient } from '@artatol-acp/auth-js';
-
-const client = new ACPAuthClient({
-  baseUrl: 'https://sso.artatol.com',
-  apiKey: '',
-  autoRefresh: true,
-  refreshThresholdSeconds: 60
-});
-
-// After login, token is automatically managed
-const result = await client.login({ email: '...', password: '...' });
-
-// Subsequent calls automatically refresh if needed
-const user = await client.me(); // No manual token management required
-```
-
-### Server-Side Token Refresh
-
-For server-side token refresh, use the `refreshAccessToken()` function:
-
-```typescript
-'use server';
-
-import { refreshAccessToken } from '@artatol-acp/auth-nextjs/server';
-
-export async function refreshTokenAction() {
-  try {
-    await refreshAccessToken();
-    return { success: true };
-  } catch (error) {
-    return { success: false, error: 'Failed to refresh token' };
-  }
-}
-```
-
-## Error Handling
-
-```typescript
-import { ACPAuthError } from '@artatol-acp/auth-js';
-
-try {
-  await login(email, password);
-} catch (error) {
-  if (error instanceof ACPAuthError) {
-    console.error('Auth error:', error.message);
-    console.error('Status code:', error.statusCode);
-
-    if (error.statusCode === 401) {
-      // Invalid credentials
-    } else if (error.statusCode === 429) {
-      // Rate limited
-    }
-  } else {
-    console.error('Unexpected error:', error);
-  }
-}
-```
-
-### Common Error Codes
-
-| Status Code | Meaning |
-|-------------|---------|
-| 401 | Unauthorized (invalid credentials or token) |
-| 403 | Forbidden (email not verified, account locked) |
-| 429 | Too Many Requests (rate limited) |
-| 500 | Internal Server Error |
-
 ## License
 
 MIT