@blinkdotnew/sdk 0.14.8 → 0.14.10

package/README.md

@@ -187,9 +187,13 @@ await blink.auth.updateMe({ displayName: 'New Name' })
 blink.auth.setToken(jwt, persist?)
 const isAuth = blink.auth.isAuthenticated()
 
-// Auth state listener
+// Auth state listener (REQUIRED for React apps!)
 const unsubscribe = blink.auth.onAuthStateChanged((state) => {
   console.log('Auth state:', state)
+  // state.user - current user or null
+  // state.isLoading - true while auth is initializing
+  // state.isAuthenticated - true if user is logged in
+  // state.tokens - current auth tokens
 })
 ```
 
@@ -1275,6 +1279,8 @@ All `{{secret_name}}` placeholders are replaced with encrypted values from your
 The most common mistake is using async functions in useEffect that lose the cleanup function:
 
 ```typescript
+import type { RealtimeChannel } from '@blinkdotnew/sdk'
+
 // ❌ WRONG - Async function loses cleanup (causes "Subscription cancelled" errors)
 useEffect(() => {
   const initApp = async () => {
@@ -1298,7 +1304,9 @@ useEffect(() => {
 ```typescript
 // ✅ CORRECT - Proper async cleanup handling
 useEffect(() => {
-  let channel = null
+  if (!user?.id) return
+  
+  let channel: RealtimeChannel | null = null
   
   const initApp = async () => {
     channel = blink.realtime.channel('room')
@@ -1311,35 +1319,119 @@ useEffect(() => {
   return () => {
     channel?.unsubscribe()
   }
-}, [user.id]) // ✅ Only user.id dependency
+}, [user?.id]) // ✅ Optional chaining in dependency too
 ```
 
 ```typescript
 // ✅ ALTERNATIVE - Using state for cleanup
-const [channel, setChannel] = useState(null)
+const [channel, setChannel] = useState<RealtimeChannel | null>(null)
 
 useEffect(() => {
+  if (!user?.id) return
+  
   const initApp = async () => {
     const ch = blink.realtime.channel('room')
     await ch.subscribe({ userId: user.id })
     setChannel(ch)
   }
   initApp().catch(console.error)
-}, [user.id])
+}, [user?.id])
 
 useEffect(() => {
   return () => channel?.unsubscribe()
 }, [channel])
 ```
 
+```typescript
+// ✅ COMPLETE EXAMPLE - With proper loading states
+function MyRealtimeComponent() {
+  const [user, setUser] = useState(null)
+  const [messages, setMessages] = useState([])
+  
+  // Auth state management
+  useEffect(() => {
+    const unsubscribe = blink.auth.onAuthStateChanged((state) => {
+      setUser(state.user)
+    })
+    return unsubscribe
+  }, [])
+  
+  // Guard clause - prevent rendering if user not loaded
+  if (!user) return <div>Loading...</div>
+  
+  // Now safe to use user.id everywhere
+  useEffect(() => {
+    if (!user?.id) return
+    
+    let channel: RealtimeChannel | null = null
+    
+    const initApp = async () => {
+      channel = blink.realtime.channel('room')
+      await channel.subscribe({ userId: user.id })
+      
+      channel.onMessage((message) => {
+        setMessages(prev => [...prev, message])
+      })
+    }
+    
+    initApp().catch(console.error)
+    
+    return () => {
+      channel?.unsubscribe()
+    }
+  }, [user?.id])
+  
+  return <div>Welcome {user.email}! Messages: {messages.length}</div>
+}
+```
+
 **Rules:**
 1. **Never return cleanup from async functions** - useEffect cleanup must be synchronous
-2. **useEffect dependency**: `[user.id]` not `[user]` to avoid reconnections  
+2. **useEffect dependency**: `[user?.id]` not `[user]` to avoid reconnections  
 3. **Store channel reference** outside async function for cleanup access
-4. **Zero connection management**: SDK handles all connection states automatically
+4. **Add component-level guards** - Check `if (!user) return <Loading />` before rendering
+5. **Zero connection management**: SDK handles all connection states automatically
 
 ### React
 
+**⚠️ 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:
+
+```typescript
+// ❌ WRONG - One-time check misses auth completion
+useEffect(() => {
+  const checkAuth = async () => {
+    try {
+      const userData = await blink.auth.me()
+      setUser(userData)
+    } catch (error) {
+      console.error('Auth check failed:', error)
+    } finally {
+      setLoading(false)
+    }
+  }
+  checkAuth() // Only runs once - misses when auth completes later!
+}, [])
+
+// ✅ CORRECT - Listen to auth state changes
+useEffect(() => {
+  const unsubscribe = blink.auth.onAuthStateChanged((state) => {
+    setUser(state.user)
+    setLoading(state.isLoading)
+  })
+  return unsubscribe
+}, [])
+```
+
+**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!**
+
 ```typescript
 import { createClient } from '@blinkdotnew/sdk'
 import { useState, useEffect } from 'react'
@@ -1348,19 +1440,46 @@ const blink = createClient({ projectId: 'your-project', authRequired: true })
 
 function App() {
   const [user, setUser] = useState(null)
+  const [loading, setLoading] = useState(true)
 
   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)
+      }
+    }
+
+    checkAuth() // ❌ Only runs once - misses when auth completes later!
+  }, [])
+
+  // This pattern causes users to get stuck on "Please sign in" 
+  // even after authentication completes
+}
+
 // React example with search functionality
 function SearchResults() {
   const [query, setQuery] = useState('')
@@ -1462,15 +1581,23 @@ function RealtimeChat() {
   const [onlineUsers, setOnlineUsers] = useState([])
   const [user] = useState({ id: 'user123', name: 'John Doe' }) // From auth
   
+  // Guard clause - prevent rendering if user not loaded
+  if (!user) return <div>Loading...</div>
+  
+  const userRef = useRef(user)
+  useEffect(() => { userRef.current = user }, [user])
+  
   useEffect(() => {
-    let channel = null
+    if (!user?.id) return
+    
+    let channel: RealtimeChannel | null = null
     
     // Subscribe and listen for messages
     const setupRealtime = async () => {
       channel = blink.realtime.channel('chat-room')
       await channel.subscribe({
-        userId: user.id,
-        metadata: { displayName: user.name, avatar: '/avatar.png' }
+        userId: userRef.current.id,
+        metadata: { displayName: userRef.current.name, avatar: '/avatar.png' }
       })
       
       // Listen for new messages
@@ -1513,7 +1640,7 @@ function RealtimeChat() {
     return () => {
       channel?.unsubscribe()
     }
-  }, [user.id, user.name])
+  }, [user?.id]) // ✅ Optional chaining in dependency
   
   const sendMessage = async () => {
     if (!newMessage.trim()) return

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blinkdotnew/sdk",
-  "version": "0.14.8",
+  "version": "0.14.10",
   "description": "Blink TypeScript SDK for client-side applications - Zero-boilerplate CRUD + auth + AI + analytics + notifications for modern SaaS/AI apps",
   "keywords": [
     "blink",