@blinkdotnew/sdk 0.14.6 → 0.14.8

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,20 @@ 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
+// ❌ 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,54 +1296,46 @@ useEffect(() => {
 ```
 
 ```typescript
-// ✅ CORRECT - Single stable connection
-const userRef = useRef(user)
-const [isConnected, setIsConnected] = useState(false)
-
-useEffect(() => { userRef.current = user }, [user])
-
+// ✅ CORRECT - Proper async cleanup handling
 useEffect(() => {
-  if (!user?.id) return
-  
-  const channel = blink.realtime.channel('room')
-  let isMounted = true, isSubscribed = false
+  let channel = null
   
-  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)
-      
-      channel.onMessage((msg) => {
-        if (!isMounted) return
-        // handle message
-      })
-    } catch (error) {
-      console.error('Connection failed:', error)
-    }
+  const initApp = async () => {
+    channel = blink.realtime.channel('room')
+    await channel.subscribe({ userId: user.id })
   }
   
-  setup()
+  initApp().catch(console.error)
+  
+  // Cleanup runs when component unmounts
   return () => {
-    isMounted = false
-    setIsConnected(false)
-    if (isSubscribed) channel.unsubscribe()
+    channel?.unsubscribe()
   }
 }, [user.id]) // ✅ Only user.id dependency
+```
 
-// Publish works automatically - no connection checks needed!
-await blink.realtime.publish('room', 'message', data)
+```typescript
+// ✅ ALTERNATIVE - Using state for cleanup
+const [channel, setChannel] = useState(null)
+
+useEffect(() => {
+  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])
 ```
 
 **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
+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. **Zero connection management**: SDK handles all connection states automatically
 
 ### React
@@ -1455,10 +1463,11 @@ function RealtimeChat() {
   const [user] = useState({ id: 'user123', name: 'John Doe' }) // From auth
   
   useEffect(() => {
-    const channel = blink.realtime.channel('chat-room')
+    let channel = 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' }
@@ -1498,11 +1507,11 @@ function RealtimeChat() {
       })))
     }
     
-    setupRealtime()
+    setupRealtime().catch(console.error)
     
     // Cleanup on unmount
     return () => {
-      channel.unsubscribe()
+      channel?.unsubscribe()
     }
   }, [user.id, user.name])
   

package/dist/index.js

@@ -1274,7 +1274,13 @@ var BlinkAuth = class {
    */
   onAuthStateChanged(callback) {
     this.listeners.add(callback);
-    callback(this.authState);
+    queueMicrotask(() => {
+      try {
+        callback(this.authState);
+      } catch (error) {
+        console.error("Error in auth state change callback:", error);
+      }
+    });
     return () => {
       this.listeners.delete(callback);
     };
@@ -2805,7 +2811,11 @@ var BlinkRealtimeChannel = class {
           metadata: options.metadata
         }
       };
-      this.websocket.send(JSON.stringify(subscribeMessage));
+      this.sendMessage(JSON.stringify(subscribeMessage)).catch((error) => {
+        if (this.pendingSubscription) {
+          this.pendingSubscription.reject(error);
+        }
+      });
     });
   }
   async unsubscribe() {
@@ -2909,6 +2919,13 @@ var BlinkRealtimeChannel = class {
    */
   sendMessage(message) {
     return new Promise((resolve, reject) => {
+      let messageObj;
+      try {
+        messageObj = JSON.parse(message);
+      } catch (error) {
+        reject(new BlinkRealtimeError("Invalid message format"));
+        return;
+      }
       const timeout = setTimeout(() => {
         const index = this.messageQueue.findIndex((q) => q.resolve === resolve);
         if (index > -1) {
@@ -2923,7 +2940,13 @@ var BlinkRealtimeChannel = class {
         timeout
       };
       if (this.websocket && this.websocket.readyState === 1) {
-        this.sendQueuedMessage(queuedMessage);
+        if (messageObj.type === "publish") {
+          this.sendQueuedMessage(queuedMessage);
+        } else {
+          this.websocket.send(message);
+          clearTimeout(timeout);
+          resolve("sent");
+        }
       } else {
         this.messageQueue.push(queuedMessage);
       }
@@ -2962,7 +2985,19 @@ var BlinkRealtimeChannel = class {
     const queue = [...this.messageQueue];
     this.messageQueue = [];
     queue.forEach((queuedMessage) => {
-      this.sendQueuedMessage(queuedMessage);
+      try {
+        const messageObj = JSON.parse(queuedMessage.message);
+        if (messageObj.type === "publish") {
+          this.sendQueuedMessage(queuedMessage);
+        } else {
+          this.websocket.send(queuedMessage.message);
+          clearTimeout(queuedMessage.timeout);
+          queuedMessage.resolve("sent");
+        }
+      } catch (error) {
+        clearTimeout(queuedMessage.timeout);
+        queuedMessage.reject(new BlinkRealtimeError("Invalid queued message format"));
+      }
     });
   }
   async connectWebSocket() {

package/dist/index.mjs

@@ -1272,7 +1272,13 @@ var BlinkAuth = class {
    */
   onAuthStateChanged(callback) {
     this.listeners.add(callback);
-    callback(this.authState);
+    queueMicrotask(() => {
+      try {
+        callback(this.authState);
+      } catch (error) {
+        console.error("Error in auth state change callback:", error);
+      }
+    });
     return () => {
       this.listeners.delete(callback);
     };
@@ -2803,7 +2809,11 @@ var BlinkRealtimeChannel = class {
           metadata: options.metadata
         }
       };
-      this.websocket.send(JSON.stringify(subscribeMessage));
+      this.sendMessage(JSON.stringify(subscribeMessage)).catch((error) => {
+        if (this.pendingSubscription) {
+          this.pendingSubscription.reject(error);
+        }
+      });
     });
   }
   async unsubscribe() {
@@ -2907,6 +2917,13 @@ var BlinkRealtimeChannel = class {
    */
   sendMessage(message) {
     return new Promise((resolve, reject) => {
+      let messageObj;
+      try {
+        messageObj = JSON.parse(message);
+      } catch (error) {
+        reject(new BlinkRealtimeError("Invalid message format"));
+        return;
+      }
       const timeout = setTimeout(() => {
         const index = this.messageQueue.findIndex((q) => q.resolve === resolve);
         if (index > -1) {
@@ -2921,7 +2938,13 @@ var BlinkRealtimeChannel = class {
         timeout
       };
       if (this.websocket && this.websocket.readyState === 1) {
-        this.sendQueuedMessage(queuedMessage);
+        if (messageObj.type === "publish") {
+          this.sendQueuedMessage(queuedMessage);
+        } else {
+          this.websocket.send(message);
+          clearTimeout(timeout);
+          resolve("sent");
+        }
       } else {
         this.messageQueue.push(queuedMessage);
       }
@@ -2960,7 +2983,19 @@ var BlinkRealtimeChannel = class {
     const queue = [...this.messageQueue];
     this.messageQueue = [];
     queue.forEach((queuedMessage) => {
-      this.sendQueuedMessage(queuedMessage);
+      try {
+        const messageObj = JSON.parse(queuedMessage.message);
+        if (messageObj.type === "publish") {
+          this.sendQueuedMessage(queuedMessage);
+        } else {
+          this.websocket.send(queuedMessage.message);
+          clearTimeout(queuedMessage.timeout);
+          queuedMessage.resolve("sent");
+        }
+      } catch (error) {
+        clearTimeout(queuedMessage.timeout);
+        queuedMessage.reject(new BlinkRealtimeError("Invalid queued message format"));
+      }
     });
   }
   async connectWebSocket() {

package/package.json

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