@blinkdotnew/sdk 0.14.7 → 0.14.9

package/README.md

@@ -958,6 +958,8 @@ blink.analytics.clearAttribution()
 **🎉 Zero-Boilerplate Connection Management!**  
 All connection states, queuing, and reconnection are handled automatically. No more "CONNECTING state" errors!
 
+**⚠️ React Users**: See the [React + Realtime Connections](#react--realtime-connections) section below for proper async cleanup patterns to avoid "Subscription cancelled" errors.
+
 ```typescript
 // 🔥 Real-time Messaging & Presence (NEW!)
 // Perfect for chat apps, live collaboration, multiplayer games, and live updates
@@ -1270,6 +1272,22 @@ All `{{secret_name}}` placeholders are replaced with encrypted values from your
 
 **⚠️ Critical: Avoid Multiple WebSocket Connections**
 
+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 () => {
+    const channel = blink.realtime.channel('room')
+    await channel.subscribe({ userId: user.id })
+    return () => channel.unsubscribe() // ❌ CLEANUP LOST!
+  }
+  initApp() // Returns Promise, not cleanup function
+}, [])
+```
+
 ```typescript
 // ❌ WRONG - Creates new connection on every user change
 useEffect(() => {
@@ -1280,55 +1298,95 @@ useEffect(() => {
 ```
 
 ```typescript
-// ✅ CORRECT - Single stable connection
-const userRef = useRef(user)
-const [isConnected, setIsConnected] = useState(false)
+// ✅ CORRECT - Proper async cleanup handling
+useEffect(() => {
+  if (!user?.id) return
+  
+  let channel: RealtimeChannel | null = null
+  
+  const initApp = async () => {
+    channel = blink.realtime.channel('room')
+    await channel.subscribe({ userId: user.id })
+  }
+  
+  initApp().catch(console.error)
+  
+  // Cleanup runs when component unmounts
+  return () => {
+    channel?.unsubscribe()
+  }
+}, [user?.id]) // ✅ Optional chaining in dependency too
+```
 
-useEffect(() => { userRef.current = user }, [user])
+```typescript
+// ✅ ALTERNATIVE - Using state for cleanup
+const [channel, setChannel] = useState<RealtimeChannel | null>(null)
 
 useEffect(() => {
   if (!user?.id) return
   
-  const channel = blink.realtime.channel('room')
-  let isMounted = true, isSubscribed = false
+  const initApp = async () => {
+    const ch = blink.realtime.channel('room')
+    await ch.subscribe({ userId: user.id })
+    setChannel(ch)
+  }
+  initApp().catch(console.error)
+}, [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([])
   
-  const setup = async () => {
-    if (!isMounted) return
-    try {
-      await channel.subscribe({ 
-        userId: userRef.current.id, 
-        metadata: { name: userRef.current.name } 
-      })
-      if (!isMounted) return
-      isSubscribed = true
-      setIsConnected(true)
+  // 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((msg) => {
-        if (!isMounted) return
-        // handle message
+      channel.onMessage((message) => {
+        setMessages(prev => [...prev, message])
       })
-    } catch (error) {
-      console.error('Connection failed:', error)
     }
-  }
+    
+    initApp().catch(console.error)
+    
+    return () => {
+      channel?.unsubscribe()
+    }
+  }, [user?.id])
   
-  setup()
-  return () => {
-    isMounted = false
-    setIsConnected(false)
-    if (isSubscribed) channel.unsubscribe()
-  }
-}, [user.id]) // ✅ Only user.id dependency
-
-// Publish works automatically - no connection checks needed!
-await blink.realtime.publish('room', 'message', data)
+  return <div>Welcome {user.email}! Messages: {messages.length}</div>
+}
 ```
 
 **Rules:**
-1. **useEffect dependency**: `[user.id]` not `[user]`
-2. **Use useRef**: Store user data to avoid re-connections
-3. **Add isMounted**: Prevent operations on unmounted components
-4. **Zero connection management**: SDK handles all connection states automatically
+1. **Never return cleanup from async functions** - useEffect cleanup must be synchronous
+2. **useEffect dependency**: `[user?.id]` not `[user]` to avoid reconnections  
+3. **Store channel reference** outside async function for cleanup access
+4. **Add component-level guards** - Check `if (!user) return <Loading />` before rendering
+5. **Zero connection management**: SDK handles all connection states automatically
 
 ### React
 
@@ -1454,14 +1512,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(() => {
-    const channel = blink.realtime.channel('chat-room')
+    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
@@ -1498,13 +1565,13 @@ function RealtimeChat() {
       })))
     }
     
-    setupRealtime()
+    setupRealtime().catch(console.error)
     
     // Cleanup on unmount
     return () => {
-      channel.unsubscribe()
+      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.7",
+  "version": "0.14.9",
   "description": "Blink TypeScript SDK for client-side applications - Zero-boilerplate CRUD + auth + AI + analytics + notifications for modern SaaS/AI apps",
   "keywords": [
     "blink",