mulink 1.0.0

package/README.md

@@ -0,0 +1,1031 @@
+# 🌉 Mulink - The Ultimate Intelligent API Client Generator
+
+**mulink** is the world's most comprehensive, intelligent, and flexible API client generator for Next.js. It automatically generates type-safe API clients, hooks, actions, and utilities from your OpenAPI schema, following Next.js 16+ best practices.
+
+> **✨ Intelligent & Self-Adapting** - mulink automatically detects and validates endpoints, features, and configurations from your OpenAPI schema. No manual configuration needed!
+
+> **🚀 No Local APIs Required** - mulink generates everything you need. No need to create local API routes or manual integrations. Everything is auto-generated and type-safe!
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![Next.js](https://img.shields.io/badge/Next.js-16.0+-black.svg)](https://nextjs.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+---
+
+## ✨ Key Features
+
+### 🧠 Intelligent Schema Analysis
+- ✅ **Auto-Detection** - Automatically detects endpoints, OAuth providers, MFA, Passkeys, and more from OpenAPI schema
+- ✅ **Smart Validation** - Validates configuration against actual schema endpoints before generating code
+- ✅ **Intelligent Warnings** - Warns you when configured features don't exist in your backend
+- ✅ **Adaptive Generation** - Only generates code for features that actually exist in your API
+- ✅ **Account Status Detection** - Automatically detects account status patterns (active, inactive, suspended, locked)
+- ✅ **Error Code Extraction** - Intelligently extracts error codes and patterns from schema
+
+### 🚀 Core Features
+- ✅ **Type-Safe API Clients** - Full TypeScript support with Zod validation
+- ✅ **React Hooks** - Auto-generated React Query hooks for all endpoints
+- ✅ **Server Actions** - Next.js 16 Server Actions with type safety
+- ✅ **Error Handling** - Comprehensive error handling with auth error support
+- ✅ **Middleware System** - Flexible request/response middleware
+- ✅ **Caching** - Smart caching with Next.js cache tags
+- ✅ **Request Deduplication** - Automatic request deduplication
+- ✅ **Retry Logic** - Configurable retry with exponential backoff
+
+### 📡 Streaming Support
+- ✅ **Server-Sent Events (SSE)** - Full SSE support with auto-reconnect
+- ✅ **Auto-Detection** - Automatically detects SSE endpoints from schema
+- ✅ **Intelligent Hooks** - Auto-generated hooks with connection state management
+- ✅ **WebSocket** - WebSocket streaming support (coming soon)
+- ✅ **HTTP Streaming** - ReadableStream support
+
+### 📤 File Uploads
+- ✅ **Presigned URLs** - Direct upload to S3/MinIO with presigned URLs
+- ✅ **Auto-Detection** - Automatically detects presigned upload endpoints
+- ✅ **Progress Tracking** - Real-time upload progress with XMLHttpRequest
+- ✅ **File Validation** - Automatic file size and type validation (extracted from schema)
+- ✅ **Compression** - Image compression (WebP) support
+- ✅ **Fallback Support** - Automatic fallback to backend upload
+- ✅ **Smart Validation** - Validates presigned endpoint existence before enabling
+
+### 🔐 Authentication (NextAuth 5.0)
+- ✅ **NextAuth 5.0** - Full NextAuth 5.0 support with intelligent configuration
+- ✅ **OAuth Providers** - Auto-detected OAuth providers (Google, GitHub, etc.)
+- ✅ **MFA Support** - TOTP and backup codes (auto-detected from schema)
+- ✅ **Passkeys** - WebAuthn/Passkeys support (auto-detected from schema)
+- ✅ **Token Management** - Automatic token injection and refresh
+- ✅ **Account Status Checking** - Auto-detected account status validation
+- ✅ **Auth Error Handling** - Automatic redirect on auth errors
+- ✅ **Session Management** - Server-side session handling with JWT/Database strategies
+
+### 🎯 Advanced Features
+- ✅ **Custom Middleware** - Add your own middleware
+- ✅ **Custom Error Handlers** - Configure custom error handling
+- ✅ **Plugin System** - Extensible plugin architecture
+- ✅ **Type Mappings** - Custom type mappings
+- ✅ **Development Tools** - Hot reload, validation, mocking
+
+---
+
+## 📦 Installation
+
+```bash
+npm install mulink
+# or
+yarn add mulink
+# or
+pnpm add mulink
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Create Configuration File
+
+Create `link.config.json` in your project root:
+
+```json
+{
+  "schema": "https://api.example.com/openapi.json",
+  "outputDir": "src/generated",
+  "framework": {
+    "type": "nextjs",
+    "version": "16.0.1",
+    "router": "app",
+    "features": {
+      "serverActions": true,
+      "middleware": true,
+      "streaming": true,
+      "revalidation": true
+    },
+    "streaming": {
+      "enabled": true,
+      "sse": {
+        "enabled": true,
+        "autoReconnect": true,
+        "reconnectDelay": 3000,
+        "maxReconnectAttempts": 5
+      }
+    }
+  },
+  "api": {
+    "baseUrl": "https://api.example.com",
+    "timeout": 30000,
+    "retries": 3,
+    "errorHandling": {
+      "enableAuthErrorHandling": true,
+      "authErrorHandlerPath": "@/lib/auth-error-handler",
+      "generateAuthErrorHandler": true
+    }
+  },
+  "auth": {
+    "enabled": true,
+    "provider": "next-auth",
+    "authPath": "@/lib/auth",
+    "tokenGetter": "auth",
+    "oauth": {
+      "enabled": true,
+      "providers": ["google", "github"]
+    },
+    "mfa": {
+      "enabled": true
+    },
+    "passkeys": {
+      "enabled": true
+    },
+    "session": {
+      "strategy": "jwt",
+      "maxAge": 30 * 24 * 60 * 60
+    }
+  },
+  "uploads": {
+    "enabled": true,
+    "strategy": "presigned",
+    "provider": "s3",
+    "presignedUploads": {
+      "enabled": true,
+      "presignEndpoint": "/api/v1/files/presign-upload",
+      "fallbackToBackend": true
+    },
+    "progressTracking": {
+      "enabled": true,
+      "useXHR": true
+    }
+  }
+}
+```
+
+### 2. Generate Code
+
+```bash
+npx mulink generate
+```
+
+**mulink will:**
+- ✅ Analyze your OpenAPI schema intelligently
+- ✅ Detect all available endpoints and features
+- ✅ Validate your configuration against actual schema
+- ✅ Warn you about missing endpoints
+- ✅ Generate only code for features that exist
+- ✅ Create type-safe clients, hooks, and actions
+
+### 3. Use Generated Code
+
+```typescript
+// In your component
+import { useGetUsers } from '@/generated/hooks/users'
+import { apiClient } from '@/generated/client'
+
+// Use React Query hook
+function UsersList() {
+  const { data, isLoading } = useGetUsers()
+  
+  if (isLoading) return <div>Loading...</div>
+  
+  return (
+    <ul>
+      {data?.data.map(user => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  )
+}
+
+// Or use client directly
+async function fetchUsers() {
+  const response = await apiClient.users.getUsers()
+  return response.data
+}
+```
+
+---
+
+## 🧠 Intelligent Features
+
+### Auto-Detection & Validation
+
+mulink intelligently analyzes your OpenAPI schema and validates your configuration:
+
+```json
+{
+  "auth": {
+    "oauth": {
+      "providers": ["google", "github", "discord"]  // discord not in schema
+    },
+    "mfa": {
+      "enabled": true  // MFA endpoints not in schema
+    }
+  }
+}
+```
+
+**mulink Output:**
+```
+⚠️  mulink Configuration Warnings:
+⚠️  OAuth provider "discord" is configured but OAuth endpoints are not found in OpenAPI schema.
+⚠️  MFA is enabled but MFA endpoints are not found in OpenAPI schema.
+These features will be disabled in generated code.
+
+✅ Generated:
+- Google OAuth (exists in schema)
+- GitHub OAuth (exists in schema)
+❌ Discord OAuth (not found - automatically excluded)
+❌ MFA (not found - automatically disabled)
+```
+
+### What mulink Auto-Detects
+
+1. **Authentication Endpoints**
+   - Login endpoints (`/auth/login`, `/auth/login/credentials`)
+   - Refresh token endpoints
+   - Logout endpoints
+   - User info endpoints (`/auth/me`, `/auth/session`)
+
+2. **OAuth Providers**
+   - OAuth authorize endpoints
+   - OAuth callback endpoints
+   - Provider names from paths
+
+3. **MFA Support**
+   - TOTP setup endpoints (`/auth/mfa/totp/setup`)
+   - TOTP verify endpoints (`/auth/mfa/totp/verify`)
+
+4. **Passkeys Support**
+   - Passkey challenge endpoints (`/auth/passkey/challenge`)
+   - Passkey authenticate endpoints (`/auth/passkey/authenticate`)
+
+5. **Account Status Patterns**
+   - Active statuses (active, enabled, verified)
+   - Inactive statuses (inactive, disabled, unverified)
+   - Suspended statuses (suspended, banned)
+   - Locked statuses (locked, frozen)
+
+6. **Error Codes**
+   - Common error codes from API responses
+   - Error patterns from schema definitions
+
+7. **File Upload Configuration**
+   - Presigned upload endpoints
+   - File size constraints
+   - Allowed file types
+
+8. **Streaming Endpoints**
+   - SSE endpoints (text/event-stream)
+   - WebSocket endpoints (coming soon)
+
+---
+
+## 📚 Configuration Options
+
+### Framework Configuration
+
+```typescript
+{
+  framework: {
+    type: 'nextjs',
+    version: '16.0.1',
+    router: 'app', // 'app' | 'pages'
+    features: {
+      serverActions: true,
+      middleware: true,
+      streaming: true,
+      revalidation: true
+    },
+    streaming: {
+      enabled: true, // Auto-detected if SSE endpoints exist
+      sse: {
+        enabled: true,
+        autoReconnect: true,
+        reconnectDelay: 3000,
+        maxReconnectAttempts: 5
+      }
+    }
+  }
+}
+```
+
+### API Configuration
+
+```typescript
+{
+  api: {
+    baseUrl: 'https://api.example.com',
+    timeout: 30000,
+    retries: 3,
+    headers: {
+      'User-Agent': 'Mulink-Client/3.4.5',
+      'Accept': 'application/json'
+    },
+    errorHandling: {
+      enableAuthErrorHandling: true,
+      authErrorHandlerPath: '@/lib/auth-error-handler',
+      generateAuthErrorHandler: true // Auto-generated with intelligent error detection
+    },
+    customMiddleware: [
+      {
+        name: 'analytics',
+        importPath: '@/lib/analytics-middleware',
+        includeInDefault: true,
+        priority: 5
+      }
+    ]
+  }
+}
+```
+
+### Authentication Configuration (NextAuth 5.0)
+
+```typescript
+{
+  auth: {
+    enabled: true,
+    provider: 'next-auth', // 'next-auth' | 'clerk' | 'custom'
+    authPath: '@/lib/auth',
+    tokenGetter: 'auth',
+    oauth: {
+      enabled: true,
+      providers: ['google', 'github'] // Auto-validated against schema
+    },
+    mfa: {
+      enabled: true // Auto-validated - only enabled if endpoints exist
+    },
+    passkeys: {
+      enabled: true // Auto-validated - only enabled if endpoints exist
+    },
+    session: {
+      strategy: 'jwt', // 'jwt' | 'database'
+      maxAge: 30 * 24 * 60 * 60 // 30 days
+    }
+  }
+}
+```
+
+**Note:** mulink automatically validates OAuth providers, MFA, and Passkeys against your schema. Features not found in the schema will be automatically disabled with warnings.
+
+### Upload Configuration
+
+```typescript
+{
+  uploads: {
+    enabled: true,
+    strategy: 'presigned', // 'standard' | 'external' | 'presigned'
+    provider: 's3', // 'uploadthing' | 'vercel-blob' | 's3' | 'minio'
+    compression: {
+      enabled: true,
+      formats: ['webp', 'gzip']
+    },
+    security: {
+      maxSize: '100MB', // Auto-extracted from schema if available
+      allowedTypes: ['image/*', 'video/*'], // Auto-extracted from schema if available
+      scan: 'none'
+    },
+    presignedUploads: {
+      enabled: true, // Auto-validated - only enabled if endpoint exists
+      presignEndpoint: '/api/v1/files/presign-upload', // Auto-detected if not specified
+      fallbackToBackend: true
+    },
+    progressTracking: {
+      enabled: true,
+      useXHR: true
+    }
+  }
+}
+```
+
+---
+
+## 🎯 Usage Examples
+
+### Basic Query Hook
+
+```typescript
+import { useGetUser } from '@/generated/hooks/users'
+
+function UserProfile({ userId }: { userId: string }) {
+  const { data, isLoading, error } = useGetUser(userId, {
+    enabled: !!userId,
+    staleTime: 5 * 60 * 1000, // 5 minutes
+  })
+
+  if (isLoading) return <div>Loading...</div>
+  if (error) return <div>Error: {error.message}</div>
+
+  return <div>{data?.data.name}</div>
+}
+```
+
+### Mutation Hook
+
+```typescript
+import { useCreateUser } from '@/generated/hooks/users'
+
+function CreateUserForm() {
+  const { mutate, isPending } = useCreateUser({
+    onSuccess: (data) => {
+      toast.success('User created!')
+      router.push(`/users/${data.data.id}`)
+    },
+    onError: (error) => {
+      toast.error(error.message)
+    }
+  })
+
+  const handleSubmit = (formData: FormData) => {
+    mutate({
+      name: formData.get('name'),
+      email: formData.get('email')
+    })
+  }
+
+  return (
+    <form action={handleSubmit}>
+      {/* form fields */}
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create User'}
+      </button>
+    </form>
+  )
+}
+```
+
+### Server-Sent Events (SSE) - Auto-Detected
+
+```typescript
+import { useStreamAnalysisUpdates } from '@/generated/hooks/analysis'
+
+function AnalysisStatus({ resultId }: { resultId: string }) {
+  // Hook auto-generated if SSE endpoint exists in schema
+  const { isConnected, sseError, reconnect } = useStreamAnalysisUpdates(
+    resultId,
+    {
+      enabled: true,
+      onMessage: (data) => {
+        console.log('Update:', data)
+        // Handle real-time updates
+      },
+      onError: (error) => {
+        console.error('SSE Error:', error)
+      }
+    }
+  )
+
+  return (
+    <div>
+      <div>Status: {isConnected ? 'Connected' : 'Disconnected'}</div>
+      {sseError && (
+        <button onClick={reconnect}>Reconnect</button>
+      )}
+    </div>
+  )
+}
+```
+
+**Features:**
+- ✅ **Auto-detection** - mulink automatically detects SSE endpoints from OpenAPI schema
+- ✅ **Auto-reconnect** - Automatic reconnection on connection loss
+- ✅ **State Management** - Full connection state (isConnected, sseError, reconnect)
+- ✅ **Event Handlers** - Support for onMessage, onError, onOpen
+- ✅ **No Manual Setup** - Everything is auto-generated!
+
+### File Upload with Presigned URLs - Auto-Validated
+
+```typescript
+import { usePredictDeepfakeUpload } from '@/generated/services/uploadPredictDeepfake'
+
+function FileUploadForm() {
+  const [progress, setProgress] = useState(0)
+  
+  // Hook auto-generated if upload endpoint exists
+  // Presigned uploads auto-enabled if presigned endpoint exists
+  const { mutate, isPending } = usePredictDeepfakeUpload({
+    onProgress: ({ percentage }) => {
+      setProgress(percentage)
+    },
+    onSuccess: (data) => {
+      toast.success('File uploaded successfully!')
+      console.log('Result:', data)
+    },
+    onError: (error) => {
+      toast.error(error.message)
+    },
+    uploadConfig: {
+      maxSize: '100MB', // Auto-extracted from schema
+      allowedTypes: ['video/*', 'image/*'], // Auto-extracted from schema
+      compression: {
+        enabled: true,
+        formats: ['webp']
+      }
+    }
+  })
+
+  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0]
+    if (file) {
+      mutate({ file })
+    }
+  }
+
+  return (
+    <div>
+      <input type="file" onChange={handleFileChange} />
+      {isPending && (
+        <div>
+          <progress value={progress} max={100} />
+          <span>{progress}%</span>
+        </div>
+      )}
+    </div>
+  )
+}
+```
+
+**Features:**
+- ✅ **Auto-detection** - Automatically detects presigned upload endpoints
+- ✅ **Auto-validation** - Validates endpoint existence before enabling
+- ✅ **Auto-fallback** - Falls back to backend upload if presigned fails
+- ✅ **Progress Tracking** - Real-time upload progress
+- ✅ **File Constraints** - Auto-extracted from schema
+
+### NextAuth 5.0 with OAuth, MFA, and Passkeys
+
+```typescript
+// lib/auth.ts (auto-generated by mulink)
+import NextAuth from 'next-auth'
+import { authOptions } from './auth-options' // Auto-generated
+
+export const { handlers, auth, signIn, signOut } = NextAuth(authOptions)
+
+// Usage in components
+import { signIn, signOut } from '@/lib/auth'
+
+// OAuth sign-in (auto-detected providers)
+await signIn('google') // ✅ Only if Google OAuth exists in schema
+await signIn('github') // ✅ Only if GitHub OAuth exists in schema
+
+// MFA setup (auto-detected)
+import { setupMFA } from '@/lib/auth/utils'
+await setupMFA() // ✅ Only if MFA endpoints exist
+
+// Passkeys (auto-detected)
+import { registerPasskey, authenticateWithPasskey } from '@/lib/auth/passkeys'
+await registerPasskey() // ✅ Only if Passkey endpoints exist
+```
+
+**Features:**
+- ✅ **Auto-detected OAuth** - Only generates code for providers that exist
+- ✅ **Auto-detected MFA** - Only enabled if MFA endpoints exist
+- ✅ **Auto-detected Passkeys** - Only enabled if Passkey endpoints exist
+- ✅ **Account Status Checking** - Auto-detected account status patterns
+- ✅ **Error Handling** - Auto-detected error codes and patterns
+
+### Direct API Client Usage
+
+```typescript
+import { apiClient } from '@/generated/client'
+
+// In Server Component or Server Action
+async function getUsers() {
+  const response = await apiClient.users.getUsers({
+    config: {
+      cacheTags: ['users'],
+      revalidate: 300
+    }
+  })
+  return response.data
+}
+
+// With custom middleware
+const response = await apiClient.users.getUsers({
+  config: {
+    middleware: [
+      {
+        name: 'custom-logging',
+        onRequest: async (config) => {
+          console.log('Request:', config)
+          return config
+        }
+      }
+    ]
+  }
+})
+```
+
+### Server Actions
+
+```typescript
+import { createUser } from '@/generated/actions/users'
+
+// In Server Component
+async function CreateUserButton() {
+  async function handleCreate(formData: FormData) {
+    'use server'
+    
+    const result = await createUser({
+      name: formData.get('name'),
+      email: formData.get('email')
+    })
+    
+    if (result?.serverError) {
+      return { error: result.serverError }
+    }
+    
+    redirect(`/users/${result.data.id}`)
+  }
+
+  return (
+    <form action={handleCreate}>
+      {/* form fields */}
+    </form>
+  )
+}
+```
+
+---
+
+## 🔧 Advanced Configuration
+
+### Custom Middleware
+
+```typescript
+// In link.config.json
+{
+  "api": {
+    "customMiddleware": [
+      {
+        "name": "analytics",
+        "importPath": "@/lib/analytics-middleware",
+        "includeInDefault": true,
+        "priority": 1
+      },
+      {
+        "name": "custom-logging",
+        "importPath": "@/lib/custom-logging",
+        "includeInDefault": false,
+        "priority": 10
+      }
+    ]
+  }
+}
+```
+
+### Custom Error Handlers
+
+```typescript
+// In link.config.json
+{
+  "api": {
+    "errorHandling": {
+      "enableAuthErrorHandling": true,
+      "authErrorHandlerPath": "@/lib/custom-auth-error-handler",
+      "generateAuthErrorHandler": false, // Use your own handler
+      "customHandlers": {
+        "rateLimit": "@/lib/rate-limit-handler",
+        "validation": "@/lib/validation-handler"
+      }
+    }
+  }
+}
+```
+
+**Note:** mulink auto-generates error handlers with intelligent error code and account status detection. You can override with custom handlers if needed.
+
+### Type Mappings
+
+```typescript
+// In link.config.json
+{
+  "typeMappings": {
+    "DateTime": "Date",
+    "UUID": "string",
+    "Money": "number",
+    "Email": "string"
+  }
+}
+```
+
+---
+
+## 🎨 Best Practices
+
+### 1. Use React Query Hooks for Client Components
+
+```typescript
+// ✅ Good - Uses generated hook
+'use client'
+import { useGetUsers } from '@/generated/hooks/users'
+
+function UsersList() {
+  const { data } = useGetUsers()
+  return <div>{/* render */}</div>
+}
+```
+
+### 2. Use Server Actions for Server Components
+
+```typescript
+// ✅ Good - Uses server action
+import { getUsers } from '@/generated/actions/users'
+
+async function UsersList() {
+  const users = await getUsers()
+  return <div>{/* render */}</div>
+}
+```
+
+### 3. Use Direct Client for Complex Scenarios
+
+```typescript
+// ✅ Good - Direct client for complex logic
+import { apiClient } from '@/generated/client'
+
+async function complexOperation() {
+  const users = await apiClient.users.getUsers()
+  const posts = await apiClient.posts.getPosts()
+  // Complex logic here
+}
+```
+
+### 4. Configure Caching Properly
+
+```typescript
+// ✅ Good - Configure cache tags
+const response = await apiClient.users.getUsers({
+  config: {
+    cacheTags: ['users', 'user-list'],
+    revalidate: 300
+  }
+})
+```
+
+### 5. Handle Errors Gracefully
+
+```typescript
+// ✅ Good - Proper error handling
+const { data, error } = useGetUsers({
+  onError: (error) => {
+    if (error.status === 401) {
+      router.push('/auth/signin')
+    } else {
+      toast.error(error.message)
+    }
+  }
+})
+```
+
+### 6. Trust mulink's Intelligence
+
+```typescript
+// ✅ Good - Let mulink auto-detect and validate
+// mulink will:
+// - Only generate code for features that exist
+// - Warn you about missing endpoints
+// - Auto-disable features not in schema
+// - Extract constraints from schema
+
+// Just configure what you want, mulink handles the rest!
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+#### 1. Import Errors
+
+**Problem**: `Cannot find module '@/generated/...'`
+
+**Solution**: Make sure your `tsconfig.json` has the correct path mapping:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"],
+      "@/generated/*": ["./src/generated/*"]
+    }
+  }
+}
+```
+
+#### 2. Auth Errors
+
+**Problem**: Auth errors not being handled
+
+**Solution**: Enable auth error handling in config:
+
+```json
+{
+  "api": {
+    "errorHandling": {
+      "enableAuthErrorHandling": true,
+      "generateAuthErrorHandler": true
+    }
+  }
+}
+```
+
+#### 3. SSE Not Working
+
+**Problem**: SSE connection fails
+
+**Solution**: Check streaming configuration. mulink will warn you if SSE endpoints don't exist:
+
+```json
+{
+  "framework": {
+    "streaming": {
+      "enabled": true,
+      "sse": {
+        "enabled": true,
+        "autoReconnect": true
+      }
+    }
+  }
+}
+```
+
+**Note:** mulink will automatically detect if SSE endpoints exist and warn you if they don't.
+
+#### 4. Upload Progress Not Working
+
+**Problem**: Upload progress not updating
+
+**Solution**: Enable progress tracking:
+
+```json
+{
+  "uploads": {
+    "progressTracking": {
+      "enabled": true,
+      "useXHR": true
+    }
+  }
+}
+```
+
+#### 5. Features Not Generated
+
+**Problem**: OAuth/MFA/Passkeys not working
+
+**Solution**: Check mulink warnings. mulink will warn you if endpoints don't exist:
+
+```
+⚠️  OAuth provider "discord" is configured but OAuth endpoints are not found in OpenAPI schema.
+⚠️  MFA is enabled but MFA endpoints are not found in OpenAPI schema.
+```
+
+**Solution**: Make sure your OpenAPI schema includes the required endpoints, or remove the configuration for features that don't exist.
+
+---
+
+## 📖 API Reference
+
+### Generated Client
+
+```typescript
+import { apiClient } from '@/generated/client'
+
+// Get endpoint client
+const usersClient = apiClient.users
+
+// Make request
+const response = await usersClient.getUser({ params: { id: '123' } })
+
+// With options
+const response = await usersClient.getUsers({
+  config: {
+    timeout: 5000,
+    retries: 2,
+    cacheTags: ['users']
+  }
+})
+```
+
+### Generated Hooks
+
+```typescript
+import { useGetUser, useCreateUser } from '@/generated/hooks/users'
+
+// Query hook
+const { data, isLoading, error, refetch } = useGetUser('123', {
+  enabled: true,
+  staleTime: 5 * 60 * 1000
+})
+
+// Mutation hook
+const { mutate, isPending } = useCreateUser({
+  onSuccess: (data) => console.log(data),
+  onError: (error) => console.error(error)
+})
+```
+
+### Generated Actions
+
+```typescript
+import { getUser, createUser } from '@/generated/actions/users'
+
+// In server component or server action
+const user = await getUser({ params: { id: '123' } })
+const newUser = await createUser({ name: 'John', email: 'john@example.com' })
+```
+
+### Generated Auth (NextAuth 5.0)
+
+```typescript
+import { signIn, signOut, auth } from '@/lib/auth'
+import { setupMFA, verifyMFA } from '@/lib/auth/utils'
+import { registerPasskey, authenticateWithPasskey } from '@/lib/auth/passkeys'
+
+// OAuth sign-in (auto-detected providers)
+await signIn('google')
+await signIn('github')
+
+// MFA (auto-detected)
+await setupMFA()
+await verifyMFA({ code: '123456' })
+
+// Passkeys (auto-detected)
+await registerPasskey()
+await authenticateWithPasskey()
+```
+
+---
+
+## 🧠 How Intelligence Works
+
+### Schema Analysis Process
+
+1. **Endpoint Detection**
+   - Scans all endpoints in OpenAPI schema
+   - Matches patterns (path, operationId, content-type)
+   - Extracts authentication, OAuth, MFA, Passkey endpoints
+
+2. **Configuration Validation**
+   - Compares your configuration with detected endpoints
+   - Warns about missing endpoints
+   - Auto-disables features not in schema
+
+3. **Pattern Extraction**
+   - Extracts account status patterns from schema definitions
+   - Extracts error codes from API responses
+   - Extracts file constraints from upload endpoints
+
+4. **Code Generation**
+   - Only generates code for validated features
+   - Includes intelligent error handling
+   - Adds account status checking where detected
+
+### Example: OAuth Auto-Detection
+
+```typescript
+// Your OpenAPI schema has:
+// GET /auth/oauth/authorize/{provider}
+// POST /auth/oauth/callback
+
+// mulink detects:
+const detectedProviders = ['google', 'github'] // From paths
+
+// Your config:
+{
+  "oauth": {
+    "providers": ["google", "github", "discord"]
+  }
+}
+
+// mulink validates:
+✅ google - exists in schema
+✅ github - exists in schema
+❌ discord - not found, warns and excludes
+
+// Generated code only includes google and github
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our contributing guidelines first.
+
+---
+
+## 📄 License
+
+MIT License - see LICENSE file for details.
+
+---
+
+## 🙏 Acknowledgments
+
+- Built for Next.js 16+
+- Uses React Query for data fetching
+- Uses Zod for validation
+- Uses TypeScript for type safety
+- Uses NextAuth 5.0 for authentication
+
+---
+
+**Made with ❤️ by the Mulverse team**
+
+**Version 3.4.7** - Intelligent API Client Generator