@blinkdotnew/sdk 0.17.4 → 0.18.1

package/README.md

@@ -27,10 +27,22 @@ import { createClient } from '@blinkdotnew/sdk'
 
 const blink = createClient({
   projectId: 'your-blink-project-id', // From blink.new dashboard
-  authRequired: true
+  authRequired: false // Don't force immediate auth - let users browse first
 })
 
-// Authentication (built-in)
+// Authentication (flexible) - Two modes available
+
+// For websites: Let users browse, require auth for protected areas
+if (!blink.auth.isAuthenticated() && needsAuth) {
+  blink.auth.login() // Redirects to blink.new auth page when needed
+}
+
+// For apps with custom auth UI (headless mode)
+const user = await blink.auth.signUp({ email: 'user@example.com', password: 'secure123' })
+const user = await blink.auth.signInWithEmail('user@example.com', 'secure123')
+const user = await blink.auth.signInWithGoogle()
+
+// Current user (works in both modes)
 const user = await blink.auth.me()
 
 // Database operations (zero config)
@@ -110,7 +122,7 @@ blink.analytics.enable()
 // Storage operations (instant - returns public URL directly)
 const { publicUrl } = await blink.storage.upload(
   file,
-  `avatars/${user.id}.png`,
+  `avatars/${user.id}-${Date.now()}.${file.name.split('.').pop()}`, // ✅ Extract original extension
   { upsert: true }
 )
 ```
@@ -128,9 +140,9 @@ const { publicUrl } = await blink.storage.upload(
 
 This SDK powers every Blink-generated app with:
 
-- **🔐 Authentication**: JWT-based auth with automatic token management
+- **🔐 Authentication**: Flexible auth system with managed (redirect) and headless (custom UI) modes, email/password, social providers (Google, GitHub, Apple, Microsoft), magic links, RBAC, and custom email branding
 - **🗄️ Database**: PostgREST-compatible CRUD operations with advanced filtering  
-- **🤖 AI**: Text generation with web search, object generation, image creation, speech synthesis, and transcription
+- **🤖 AI**: Text generation with web search, object generation, image creation (Gemini 2.5 Flash), speech synthesis, and transcription
 - **📄 Data**: Extract text content from documents, secure API proxy with secret substitution, web scraping, screenshots, and web search
 - **📁 Storage**: File upload, download, and management
 - **📧 Notifications**: Email sending with attachments, custom branding, and delivery tracking
@@ -152,10 +164,15 @@ import { createClient } from '@blinkdotnew/sdk'
 
 const blink = createClient({
   projectId: 'your-blink-project-id', // From blink.new dashboard
-  authRequired: true // Automatic auth redirect
+  authRequired: false, // Let users browse first - require auth only for protected areas
+  auth: {
+    mode: 'managed' // Use new explicit configuration
+  }
 })
 ```
 
+> **⚠️ Version Requirement**: The flexible authentication system (managed vs headless modes) requires SDK version **0.18.0 or higher**. If you're using version 0.17.x or below, you'll only have access to the legacy authentication system. Please upgrade to access the new authentication features.
+
 ### Server-side (Node.js, Deno, Edge functions)
 
 ```typescript
@@ -163,7 +180,7 @@ import { createClient } from '@blinkdotnew/sdk'
 
 const blink = createClient({
   projectId: 'your-blink-project-id', // From blink.new dashboard
-  authRequired: false // Manual token management
+  auth: { mode: 'managed' } // Manual token management
 })
 
 // Set JWT manually
@@ -174,11 +191,224 @@ blink.auth.setToken(jwtFromHeader)
 
 ### Authentication
 
+> **⚠️ Version Requirement**: The flexible authentication system requires SDK version **0.18.0 or higher**. Version 0.17.x and below only support the legacy authentication system.
+
+Blink provides **two authentication modes** for maximum flexibility:
+
+#### Managed Mode (Default - Redirect-based)
+
+Perfect for quick setup with Blink's hosted auth page:
+
+```typescript
+// ⚠️ DEPRECATED: authRequired is legacy - use auth.mode instead
+const blink = createClient({
+  projectId: 'your-project',
+  authRequired: false // Legacy - still works but deprecated
+})
+
+// ✅ RECOMMENDED: Use new auth configuration
+const blink = createClient({
+  projectId: 'your-project',
+  auth: {
+    mode: 'managed', // Explicit mode configuration
+    redirectUrl: 'https://myapp.com/dashboard'
+  }
+})
+
+// Simple redirect authentication
+blink.auth.login() // Redirects to blink.new auth page
+blink.auth.logout() // Clear tokens and redirect
+```
+
+#### Headless Mode (Custom UI Control)
+
+Build your own authentication UI with full control:
+
+```typescript
+const blink = createClient({
+  projectId: 'your-project',
+  auth: {
+    mode: 'headless'
+    // Providers controlled via project settings
+  }
+})
+
+// Email/password authentication
+const user = await blink.auth.signUp({
+  email: 'user@example.com',
+  password: 'SecurePass123!',
+  metadata: { displayName: 'John Doe' }
+})
+
+const user = await blink.auth.signInWithEmail('user@example.com', 'password')
+
+// Social provider authentication
+const user = await blink.auth.signInWithGoogle()
+const user = await blink.auth.signInWithGitHub()
+const user = await blink.auth.signInWithApple()
+const user = await blink.auth.signInWithMicrosoft()
+
+// Magic links (passwordless)
+await blink.auth.sendMagicLink('user@example.com', {
+  redirectUrl: 'https://myapp.com/dashboard'
+})
+```
+
+#### 🔧 Provider Configuration
+
+**Step 1: Enable Providers in Your Project**
+1. Go to [blink.new](https://blink.new) and open your project
+2. Navigate to **Project → Workspace → Authentication**
+3. Toggle providers on/off:
+   - **Email** ✅ (enabled by default) - Includes email/password, magic links, and verification
+   - **Google** ✅ (enabled by default)
+   - **GitHub** ⚪ (disabled by default)
+   - **Apple** ⚪ (disabled by default)
+   - **Microsoft** ⚪ (disabled by default)
+4. Configure email settings:
+   - **Require email verification**: Off by default (easier implementation)
+   - **Allow user signup**: On by default
+
+**Step 2: Discover Available Providers**
+```typescript
+// Get providers enabled for your project
+const availableProviders = await blink.auth.getAvailableProviders()
+// Returns: ['email', 'google'] (based on your project settings)
+
+// Use in your UI to show only enabled providers
+const showGoogleButton = availableProviders.includes('google')
+const showGitHubButton = availableProviders.includes('github')
+```
+
+**Step 3: Client-Side Filtering (Headless Mode)**
+```typescript
+const blink = createClient({
+  projectId: 'your-project',
+  auth: {
+    mode: 'headless'
+    // All providers controlled via project settings
+  }
+})
+```
+
+**Managed Mode: Automatic Provider Display**
+```typescript
+const blink = createClient({
+  projectId: 'your-project',
+  auth: { mode: 'managed' }
+})
+
+// The hosted auth page automatically shows only enabled providers
+blink.auth.login() // Shows Email + Google by default
+```
+
+#### 📧 Email Verification Flow
+
+**By default, email verification is NOT required** for easier implementation. Enable it only if needed:
+
+**Step 1: Configure Verification (Optional)**
+1. Go to [blink.new](https://blink.new) → Project → Workspace → Authentication
+2. Toggle **"Require email verification"** ON (disabled by default)
+
+**Step 2: Handle the Complete Flow**
+```typescript
+// User signup - always send verification email for security
+try {
+  const user = await blink.auth.signUp({ email, password })
+  await blink.auth.sendEmailVerification()
+  setMessage('Account created! Check your email to verify.')
+} catch (error) {
+  setError(error.message)
+}
+
+// User signin - handle verification requirement
+try {
+  await blink.auth.signInWithEmail(email, password)
+  // Success - user is signed in
+} catch (error) {
+  if (error.code === 'EMAIL_NOT_VERIFIED') {
+    setError('Please verify your email first')
+    await blink.auth.sendEmailVerification() // Resend verification
+  } else {
+    setError(error.message)
+  }
+}
+
+// Manual verification resend
+await blink.auth.sendEmailVerification()
+```
+
+**What Happens:**
+1. **Signup**: User account created, `email_verified = false`
+2. **Verification Email**: User clicks link → `email_verified = true`  
+3. **Signin Check**: If verification required AND not verified → `EMAIL_NOT_VERIFIED` error
+4. **Success**: User can sign in once verified (or if verification not required)
+
+#### Flexible Email System
+
+**Maximum flexibility** - you control email branding while Blink handles secure tokens:
+
+```typescript
+// Option A: Custom email delivery (full branding control)
+const resetData = await blink.auth.generatePasswordResetToken('user@example.com')
+// Returns: { token, expiresAt, resetUrl }
+
+// Send with your email service and branding
+await yourEmailService.send({
+  to: 'user@example.com',
+  subject: 'Reset your YourApp password',
+  html: `
+    <div style="font-family: Arial, sans-serif;">
+      <img src="https://yourapp.com/logo.png" alt="YourApp" />
+      <h1>Reset Your Password</h1>
+      <a href="${resetData.resetUrl}" 
+         style="background: #0070f3; color: white; padding: 16px 32px; 
+                text-decoration: none; border-radius: 8px;">
+        Reset Password
+      </a>
+    </div>
+  `
+})
+
+// Option B: Blink default email (zero setup)
+await blink.auth.sendPasswordResetEmail('user@example.com')
+
+// Same flexibility for email verification and magic links
+const verifyData = await blink.auth.generateEmailVerificationToken()
+const magicData = await blink.auth.generateMagicLinkToken('user@example.com')
+```
+
+#### Role-Based Access Control (RBAC)
+
 ```typescript
-// Login/logout
-blink.auth.login(nextUrl?)           // Redirect to auth page
-blink.auth.logout(redirectUrl?)      // Clear tokens and redirect
+// Configure roles and permissions
+const blink = createClient({
+  projectId: 'your-project',
+  auth: {
+    mode: 'headless',
+    roles: {
+      admin: { permissions: ['*'] },
+      editor: { permissions: ['posts.create', 'posts.update'] },
+      viewer: { permissions: ['posts.read'] }
+    }
+  }
+})
+
+// Check permissions
+const canEdit = blink.auth.can('posts.update')
+const isAdmin = blink.auth.hasRole('admin')
+const isStaff = blink.auth.hasRole(['admin', 'editor'])
+
+// Use in components
+function EditButton() {
+  if (!blink.auth.can('posts.update')) return null
+  return <button onClick={editPost}>Edit Post</button>
+}
+```
 
+#### Core Methods
+
+```typescript
 // User management
 const user = await blink.auth.me()
 await blink.auth.updateMe({ displayName: 'New Name' })
@@ -187,6 +417,16 @@ await blink.auth.updateMe({ displayName: 'New Name' })
 blink.auth.setToken(jwt, persist?)
 const isAuth = blink.auth.isAuthenticated()
 
+// Password management
+await blink.auth.changePassword('oldPass', 'newPass')
+await blink.auth.confirmPasswordReset(token, newPassword)
+
+// Email verification
+await blink.auth.verifyEmail(token)
+
+// Provider discovery
+const providers = await blink.auth.getAvailableProviders()
+
 // Auth state listener (REQUIRED for React apps!)
 const unsubscribe = blink.auth.onAuthStateChanged((state) => {
   console.log('Auth state:', state)
@@ -285,7 +525,6 @@ await blink.db.todos.upsertMany([...])
 // Text generation (simple prompt)
 const { text } = await blink.ai.generateText({
   prompt: 'Write a poem about coding',
-  model: 'gpt-4o-mini',
   maxTokens: 150
 })
 
@@ -306,6 +545,7 @@ const { text } = await blink.ai.generateText({
 // Text generation with image content
 // ⚠️ IMPORTANT: Images must be HTTPS URLs with file extensions (.jpg, .jpeg, .png, .gif, .webp)
 // For file uploads, use blink.storage.upload() first to get public HTTPS URLs
+// 🚫 CRITICAL: When uploading files, NEVER hardcode extensions - use file.name or auto-detection
 const { text } = await blink.ai.generateText({
   messages: [
     { 
@@ -380,26 +620,97 @@ const { object: todoList } = await blink.ai.generateObject({
 // })
 // Error: "schema must be a JSON Schema of 'type: \"object\"', got 'type: \"array\"'"
 
-// Generate and modify images with AI
+// Generate and modify images with AI (powered by Gemini 2.5 Flash Image)
+// 🔥 Automatic optimization - no need to specify size, quality, or style parameters
+// 🎨 For style transfer: provide ALL images in the images array, don't reference URLs in prompts
 
 // Basic image generation - returns public URLs directly
 const { data } = await blink.ai.generateImage({
-  prompt: 'A serene landscape with mountains and a lake at sunset',
-  size: '1024x1024',
-  quality: 'high',
-  n: 2
+  prompt: 'A serene landscape with mountains and a lake at sunset'
 })
 console.log('Image URL:', data[0].url)
 
+// Multiple images
+const { data } = await blink.ai.generateImage({
+  prompt: 'A futuristic robot in different poses',
+  n: 3
+})
+data.forEach((img, i) => console.log(`Image ${i+1}:`, img.url))
+
 // Image editing - transform existing images with prompts
 const { data: headshots } = await blink.ai.modifyImage({
-  images: ['https://storage.example.com/user-photo.jpg'], // ... up to 16 images maximum!
-  prompt: 'Generate professional business headshot with studio lighting for this person.',
-  quality: 'high',
-  n: 4
+  images: ['https://storage.example.com/user-photo.jpg'], // Up to 50 images supported!
+  prompt: 'Transform into professional business headshot with studio lighting'
+})
+
+// Advanced image editing with multiple input images
+const { data } = await blink.ai.modifyImage({
+  images: [
+    'https://storage.example.com/photo1.jpg',
+    'https://storage.example.com/photo2.jpg',
+    'https://storage.example.com/photo3.jpg'
+  ],
+  prompt: 'Combine these architectural styles into a futuristic building design',
+  n: 2
+})
+
+// 🎨 Style Transfer & Feature Application
+// ⚠️ IMPORTANT: When applying styles/features from one image to another,
+// provide ALL images in the array - don't reference images in the prompt text
+
+// ❌ WRONG - Don't reference images in prompt
+const wrongWay = await blink.ai.modifyImage({
+  images: [userPhotoUrl],
+  prompt: `Apply this hairstyle from the reference image to the person's head. Reference hairstyle: ${hairstyleUrl}`
+})
+
+// ✅ CORRECT - Provide all images in the array
+const { data } = await blink.ai.modifyImage({
+  images: [userPhotoUrl, hairstyleUrl], // Both images provided
+  prompt: 'Apply the hairstyle from the second image to the person in the first image. Blend naturally with face shape.'
+})
+
+// More style transfer examples
+const { data } = await blink.ai.modifyImage({
+  images: [portraitUrl, artworkUrl],
+  prompt: 'Apply the artistic style and color palette from the second image to the portrait in the first image'
+})
+
+const { data } = await blink.ai.modifyImage({
+  images: [roomPhotoUrl, designReferenceUrl],
+  prompt: 'Redesign the room in the first image using the interior design style shown in the second image'
+})
+
+// Multiple reference images for complex transformations
+const { data } = await blink.ai.modifyImage({
+  images: [
+    originalPhotoUrl,
+    lightingReferenceUrl,
+    colorPaletteReferenceUrl,
+    compositionReferenceUrl
+  ],
+  prompt: 'Transform the first image using the lighting style from image 2, color palette from image 3, and composition from image 4'
+})
+
+// 📱 File Upload + Style Transfer
+// ⚠️ Extract file extension properly - never hardcode .jpg/.png
+
+// ❌ WRONG - Hardcoded extension
+const userUpload = await blink.storage.upload(file, `photos/${Date.now()}.jpg`) // Breaks HEIC/PNG files
+// ✅ CORRECT - Extract original extension
+const userUpload = await blink.storage.upload(
+  userPhoto.file, 
+  `photos/${Date.now()}.${userPhoto.file.name.split('.').pop()}`
+)
+const hairstyleUpload = await blink.storage.upload(
+  hairstylePhoto.file,
+  `haircuts/${Date.now()}.${hairstylePhoto.file.name.split('.').pop()}`
+)
+
+const { data } = await blink.ai.modifyImage({
+  images: [userUpload.publicUrl, hairstyleUpload.publicUrl],
+  prompt: 'Apply hairstyle from second image to person in first image'
 })
-// Options: size ('1024x1024', '1536x1024'), quality ('auto'|'low'|'medium'|'high'), 
-// background ('auto'|'transparent'|'opaque'), n (1-10 images)
 
 
 // Speech synthesis
@@ -732,20 +1043,17 @@ try {
 // Upload files (returns public URL directly)
 const { publicUrl } = await blink.storage.upload(
   file,
-  'path/to/file',
+  `uploads/${Date.now()}.${file.name.split('.').pop()}`, // ✅ Extract original extension
   {
     upsert: true,
     onProgress: (percent) => console.log(`${percent}%`)
   }
 )
-// If file is PNG, final path will be: path/to/file.png
 
-// 💡 Pro tip: Use the actual filename (file.name) in your path to avoid confusion
-const { publicUrl } = await blink.storage.upload(
-  file,
-  `uploads/${file.name}`, // Uses actual filename with correct extension
-  { upsert: true }
-)
+// ❌ WRONG - Hardcoded extensions break HEIC/PNG/WebP files
+const wrong = await blink.storage.upload(file, `uploads/${Date.now()}.jpg`) // Corrupts non-JPG files
+// ✅ CORRECT - Extract file extension
+const correct = await blink.storage.upload(file, `uploads/${Date.now()}.${file.name.split('.').pop()}`)
 
 // Remove files
 await blink.storage.remove('file1.jpg', 'file2.jpg')
@@ -1209,14 +1517,44 @@ try {
 ### Error Handling
 
 ```typescript
-import { BlinkAuthError, BlinkAIError, BlinkStorageError, BlinkDataError, BlinkRealtimeError, BlinkNotificationsError } from '@blinkdotnew/sdk'
-
+import { 
+  BlinkAuthError, 
+  BlinkAuthErrorCode,
+  BlinkAIError, 
+  BlinkStorageError, 
+  BlinkDataError, 
+  BlinkRealtimeError, 
+  BlinkNotificationsError 
+} from '@blinkdotnew/sdk'
+
+// Authentication error handling
 try {
-  const user = await blink.auth.me()
+  const user = await blink.auth.signInWithEmail(email, password)
 } catch (error) {
   if (error instanceof BlinkAuthError) {
-    // Handle auth errors
-    console.error('Auth error:', error.message)
+    switch (error.code) {
+      case BlinkAuthErrorCode.EMAIL_NOT_VERIFIED:
+        console.log('Email verification required')
+        await blink.auth.sendEmailVerification()
+        break
+      case BlinkAuthErrorCode.INVALID_CREDENTIALS:
+        console.error('Invalid email or password')
+        break
+      case BlinkAuthErrorCode.RATE_LIMITED:
+        console.error('Too many attempts, try again later')
+        break
+      default:
+        console.error('Auth error:', error.message)
+    }
+  }
+}
+
+// Other error types
+try {
+  const { text } = await blink.ai.generateText({ prompt: 'Hello' })
+} catch (error) {
+  if (error instanceof BlinkAIError) {
+    console.error('AI error:', error.message)
   }
 }
 ```
@@ -1227,7 +1565,18 @@ try {
 const blink = createClient({
   projectId: 'your-project',
   baseUrl: 'https://custom-api.example.com',
-  authRequired: true,
+  auth: {
+    mode: 'headless', // 'managed' | 'headless'
+    authUrl: 'https://custom-auth.example.com', // Custom auth domain
+    coreUrl: 'https://custom-core.example.com', // Custom API domain
+    // Providers controlled via project settings
+    redirectUrl: 'https://myapp.com/dashboard',
+    roles: {
+      admin: { permissions: ['*'] },
+      editor: { permissions: ['posts.create', 'posts.update'], inherit: ['viewer'] },
+      viewer: { permissions: ['posts.read'] }
+    }
+  },
   httpClient: {
     timeout: 30000,
     retries: 3
@@ -1428,6 +1777,220 @@ function MyRealtimeComponent() {
 
 ### React
 
+#### Authentication Integration
+
+**Complete authentication example with custom UI:**
+
+```typescript
+import { createClient } from '@blinkdotnew/sdk'
+import { useState, useEffect } from 'react'
+
+// ✅ RECOMMENDED: Don't force immediate auth - let users browse first
+const blink = createClient({
+  projectId: 'your-project',
+  authRequired: false, // Let users browse public areas
+  auth: {
+    mode: 'headless' // Use headless for custom UI
+    // Providers controlled via project settings
+  }
+})
+
+function App() {
+  const [user, setUser] = useState(null)
+  const [loading, setLoading] = useState(true)
+  const [currentPage, setCurrentPage] = useState('home')
+
+  // ✅ CRITICAL: Always use onAuthStateChanged
+  useEffect(() => {
+    const unsubscribe = blink.auth.onAuthStateChanged((state) => {
+      setUser(state.user)
+      setLoading(state.isLoading)
+    })
+    return unsubscribe
+  }, [])
+
+  // Protected route check - only require auth for dashboard/account areas
+  const requiresAuth = ['dashboard', 'account', 'settings'].includes(currentPage)
+
+  if (loading) return <div>Loading...</div>
+  if (requiresAuth && !user) return <AuthForm />
+
+  // Public pages (home, pricing, about) don't require auth
+  if (currentPage === 'home') return <HomePage />
+  if (currentPage === 'pricing') return <PricingPage />
+  
+  // Protected pages require authentication
+  return <Dashboard user={user} />
+}
+
+function AuthForm() {
+  const [mode, setMode] = useState('signin') // 'signin' | 'signup' | 'reset'
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [error, setError] = useState('')
+  const [message, setMessage] = useState('')
+
+  const handleEmailAuth = async (e) => {
+    e.preventDefault()
+    setError('')
+    
+    try {
+      if (mode === 'signup') {
+        const user = await blink.auth.signUp({ email, password })
+        setMessage('Account created! Please check your email to verify.')
+        await blink.auth.sendEmailVerification()
+      } else if (mode === 'signin') {
+        await blink.auth.signInWithEmail(email, password)
+        // User state updates automatically via onAuthStateChanged
+      } else if (mode === 'reset') {
+        await blink.auth.sendPasswordResetEmail(email)
+        setMessage('Password reset email sent!')
+      }
+    } catch (err) {
+      if (err.code === 'EMAIL_NOT_VERIFIED') {
+        setError('Please verify your email first')
+        await blink.auth.sendEmailVerification()
+      } else {
+        setError(err.message)
+      }
+    }
+  }
+
+  const handleSocialAuth = async (provider) => {
+    try {
+      await blink.auth.signInWithProvider(provider)
+    } catch (err) {
+      setError(err.message)
+    }
+  }
+
+  return (
+    <div style={{ maxWidth: '400px', margin: '0 auto', padding: '2rem' }}>
+      <h1>{mode === 'signin' ? 'Sign In' : mode === 'signup' ? 'Sign Up' : 'Reset Password'}</h1>
+      
+      {error && <div style={{ color: 'red', marginBottom: '1rem' }}>{error}</div>}
+      {message && <div style={{ color: 'green', marginBottom: '1rem' }}>{message}</div>}
+      
+      <form onSubmit={handleEmailAuth} style={{ marginBottom: '1rem' }}>
+        <input
+          type="email"
+          placeholder="Email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          style={{ width: '100%', padding: '0.5rem', marginBottom: '0.5rem' }}
+        />
+        
+        {mode !== 'reset' && (
+          <input
+            type="password"
+            placeholder="Password"
+            value={password}
+            onChange={(e) => setPassword(e.target.value)}
+            style={{ width: '100%', padding: '0.5rem', marginBottom: '1rem' }}
+          />
+        )}
+        
+        <button type="submit" style={{ width: '100%', padding: '0.75rem', marginBottom: '1rem' }}>
+          {mode === 'signin' ? 'Sign In' : mode === 'signup' ? 'Create Account' : 'Send Reset Email'}
+        </button>
+      </form>
+
+      {mode !== 'reset' && (
+        <div style={{ display: 'flex', gap: '0.5rem', marginBottom: '1rem' }}>
+          <button onClick={() => handleSocialAuth('google')} style={{ flex: 1, padding: '0.5rem' }}>
+            Google
+          </button>
+          <button onClick={() => handleSocialAuth('github')} style={{ flex: 1, padding: '0.5rem' }}>
+            GitHub
+          </button>
+        </div>
+      )}
+
+      <div style={{ textAlign: 'center', fontSize: '0.875rem' }}>
+        {mode === 'signin' && (
+          <>
+            <button onClick={() => setMode('signup')} style={{ marginRight: '1rem' }}>
+              Create Account
+            </button>
+            <button onClick={() => setMode('reset')}>Forgot Password?</button>
+          </>
+        )}
+        {mode === 'signup' && (
+          <button onClick={() => setMode('signin')}>Already have an account?</button>
+        )}
+        {mode === 'reset' && (
+          <button onClick={() => setMode('signin')}>Back to Sign In</button>
+        )}
+      </div>
+    </div>
+  )
+}
+```
+
+#### Custom Email Branding Example
+
+**Send password reset with your own email service:**
+
+```typescript
+function PasswordResetForm() {
+  const [email, setEmail] = useState('')
+  const [message, setMessage] = useState('')
+
+  const handleReset = async (e) => {
+    e.preventDefault()
+    
+    try {
+      // Generate secure token (no email sent by Blink)
+      const resetData = await blink.auth.generatePasswordResetToken(email)
+      
+      // Send with your own email service and branding
+      await yourEmailService.send({
+        to: email,
+        from: 'support@yourapp.com',
+        subject: 'Reset your YourApp password',
+        html: `
+          <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; max-width: 600px; margin: 0 auto;">
+            <div style="text-align: center; padding: 40px;">
+              <img src="https://yourapp.com/logo.svg" alt="YourApp" style="width: 120px; margin-bottom: 32px;" />
+              <h1 style="color: #1a1a1a; font-size: 28px; margin-bottom: 16px;">Reset Your Password</h1>
+              <p style="color: #666; font-size: 16px; margin-bottom: 32px;">
+                We received a request to reset your YourApp password.
+              </p>
+              <a href="${resetData.resetUrl}" 
+                 style="display: inline-block; background: #0070f3; color: white; 
+                        padding: 16px 32px; text-decoration: none; border-radius: 8px; 
+                        font-weight: 600; font-size: 16px;">
+                Reset My Password
+              </a>
+              <p style="color: #999; font-size: 14px; margin-top: 32px;">
+                This link expires in 1 hour. If you didn't request this, you can ignore this email.
+              </p>
+            </div>
+          </div>
+        `
+      })
+      
+      setMessage('Password reset email sent! Check your inbox.')
+    } catch (error) {
+      console.error('Reset failed:', error.message)
+    }
+  }
+
+  return (
+    <form onSubmit={handleReset}>
+      <input
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        placeholder="Enter your email"
+      />
+      <button type="submit">Send Reset Link</button>
+      {message && <p>{message}</p>}
+    </form>
+  )
+}
+```
+
 **⚠️ Critical: Always Use Auth State Listener, Never One-Time Checks**
 
 The most common authentication mistake is checking auth status once instead of listening to changes:
@@ -1458,62 +2021,47 @@ useEffect(() => {
 }, [])
 ```
 
-**Why the one-time check fails:**
-1. App loads → `blink.auth.me()` called immediately
-2. Auth still initializing → Call fails, user set to `null`
-3. Auth completes later → App never knows because it only checked once
-4. User stuck on "Please sign in" screen forever
-
-**Always use `onAuthStateChanged()` for React apps!**
+#### Error Handling Example
 
 ```typescript
-import { createClient } from '@blinkdotnew/sdk'
-import { useState, useEffect } from 'react'
+import { BlinkAuthError, BlinkAuthErrorCode } from '@blinkdotnew/sdk'
 
-const blink = createClient({ projectId: 'your-project', authRequired: true })
-
-function App() {
-  const [user, setUser] = useState(null)
-  const [loading, setLoading] = useState(true)
+function AuthForm() {
+  const [error, setError] = useState('')
 
-  useEffect(() => {
-    const unsubscribe = blink.auth.onAuthStateChanged((state) => {
-      setUser(state.user)
-      setLoading(state.isLoading)
-    })
-    return unsubscribe
-  }, [])
-
-  if (loading) return <div>Loading...</div>
-  if (!user) return <div>Please log in</div>
-
-  return <div>Welcome, {user.email}!</div>
-}
-
-// ❌ WRONG - One-time auth check (misses auth state changes)
-function BadApp() {
-  const [user, setUser] = useState(null)
-  const [loading, setLoading] = useState(true)
-
-  useEffect(() => {
-    const checkAuth = async () => {
-      try {
-        const userData = await blink.auth.me()
-        setUser(userData)
-      } catch (error) {
-        console.error('Auth check failed:', error)
-      } finally {
-        setLoading(false)
+  const handleAuth = async () => {
+    try {
+      await blink.auth.signInWithEmail(email, password)
+    } catch (err) {
+      if (err instanceof BlinkAuthError) {
+        switch (err.code) {
+          case BlinkAuthErrorCode.EMAIL_NOT_VERIFIED:
+            setError('Please verify your email first')
+            await blink.auth.sendEmailVerification()
+            break
+          case BlinkAuthErrorCode.INVALID_CREDENTIALS:
+            setError('Invalid email or password')
+            break
+          case BlinkAuthErrorCode.RATE_LIMITED:
+            setError('Too many attempts. Please try again later.')
+            break
+          default:
+            setError('Authentication failed. Please try again.')
+        }
       }
     }
+  }
 
-    checkAuth() // ❌ Only runs once - misses when auth completes later!
-  }, [])
-
-  // This pattern causes users to get stuck on "Please sign in" 
-  // even after authentication completes
+  return (
+    <div>
+      {error && <div style={{ color: 'red' }}>{error}</div>}
+      {/* Auth form */}
+    </div>
+  )
 }
+```
 
+```typescript
 // React example with search functionality
 function SearchResults() {
   const [query, setQuery] = useState('')
@@ -1749,7 +2297,11 @@ function RealtimeChat() {
 // pages/api/todos.ts
 import { createClient } from '@blinkdotnew/sdk'
 
-const blink = createClient({ projectId: 'your-project', authRequired: false })
+// ✅ RECOMMENDED: Use new auth configuration
+const blink = createClient({ 
+  projectId: 'your-project',
+  auth: { mode: 'managed' } // Explicit configuration
+})
 
 export default async function handler(req, res) {
   const jwt = req.headers.authorization?.replace('Bearer ', '')
@@ -1765,7 +2317,11 @@ export default async function handler(req, res) {
 ```typescript
 import { createClient } from '@blinkdotnew/sdk'
 
-const blink = createClient({ projectId: 'your-project', authRequired: false })
+// ✅ RECOMMENDED: Use new auth configuration
+const blink = createClient({ 
+  projectId: 'your-project',
+  auth: { mode: 'managed' } // Explicit configuration
+})
 
 Deno.serve(async (req) => {
   const jwt = req.headers.get('authorization')?.replace('Bearer ', '')