@blinkdotnew/sdk 0.14.4 → 0.14.6

package/README.md

@@ -955,6 +955,9 @@ blink.analytics.clearAttribution()
 
 ### Realtime Operations
 
+**🎉 Zero-Boilerplate Connection Management!**  
+All connection states, queuing, and reconnection are handled automatically. No more "CONNECTING state" errors!
+
 ```typescript
 // 🔥 Real-time Messaging & Presence (NEW!)
 // Perfect for chat apps, live collaboration, multiplayer games, and live updates
@@ -1263,6 +1266,70 @@ All `{{secret_name}}` placeholders are replaced with encrypted values from your
 
 ## 🌍 Framework Examples
 
+### React + Realtime Connections
+
+**⚠️ Critical: Avoid Multiple WebSocket Connections**
+
+```typescript
+// ❌ WRONG - Creates new connection on every user change
+useEffect(() => {
+  const channel = blink.realtime.channel('room')
+  await channel.subscribe({ userId: user.id, metadata: { name: user.name } })
+  return () => channel.unsubscribe()
+}, [user]) // ❌ Full user object dependency causes reconnections
+```
+
+```typescript
+// ✅ CORRECT - Single stable connection
+const userRef = useRef(user)
+const [isConnected, setIsConnected] = useState(false)
+
+useEffect(() => { userRef.current = user }, [user])
+
+useEffect(() => {
+  if (!user?.id) return
+  
+  const channel = blink.realtime.channel('room')
+  let isMounted = true, isSubscribed = false
+  
+  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)
+    }
+  }
+  
+  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)
+```
+
+**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
+
 ### React
 
 ```typescript

package/dist/index.d.mts

@@ -469,6 +469,7 @@ interface RealtimeChannel {
         before?: string;
         after?: string;
     }): Promise<RealtimeMessage[]>;
+    isReady(): boolean;
 }
 interface RealtimeSubscribeOptions {
     userId?: string;
@@ -1512,10 +1513,19 @@ declare class BlinkRealtimeChannel implements RealtimeChannel {
     private presenceCallbacks;
     private websocket;
     private isSubscribed;
+    private isConnected;
+    private isConnecting;
     private reconnectTimer;
     private heartbeatTimer;
     private reconnectAttempts;
+    private messageQueue;
+    private pendingSubscription;
+    private connectionPromise;
     constructor(channelName: string, httpClient: HttpClient, projectId: string);
+    /**
+     * Check if channel is ready for publishing
+     */
+    isReady(): boolean;
     subscribe(options?: {
         userId?: string;
         metadata?: Record<string, any>;
@@ -1533,7 +1543,27 @@ declare class BlinkRealtimeChannel implements RealtimeChannel {
         before?: string;
         after?: string;
     }): Promise<RealtimeMessage[]>;
+    /**
+     * Ensure WebSocket connection is established and ready
+     */
+    private ensureConnected;
+    /**
+     * Send a message, queuing if socket not ready
+     */
+    private sendMessage;
+    /**
+     * Send a queued message and set up response handling
+     */
+    private sendQueuedMessage;
+    /**
+     * Flush all queued messages when connection becomes ready
+     */
+    private flushMessageQueue;
     private connectWebSocket;
+    /**
+     * Reject all queued messages with the given error
+     */
+    private rejectQueuedMessages;
     private handleWebSocketMessage;
     private startHeartbeat;
     private scheduleReconnect;

package/dist/index.d.ts

@@ -469,6 +469,7 @@ interface RealtimeChannel {
         before?: string;
         after?: string;
     }): Promise<RealtimeMessage[]>;
+    isReady(): boolean;
 }
 interface RealtimeSubscribeOptions {
     userId?: string;
@@ -1512,10 +1513,19 @@ declare class BlinkRealtimeChannel implements RealtimeChannel {
     private presenceCallbacks;
     private websocket;
     private isSubscribed;
+    private isConnected;
+    private isConnecting;
     private reconnectTimer;
     private heartbeatTimer;
     private reconnectAttempts;
+    private messageQueue;
+    private pendingSubscription;
+    private connectionPromise;
     constructor(channelName: string, httpClient: HttpClient, projectId: string);
+    /**
+     * Check if channel is ready for publishing
+     */
+    isReady(): boolean;
     subscribe(options?: {
         userId?: string;
         metadata?: Record<string, any>;
@@ -1533,7 +1543,27 @@ declare class BlinkRealtimeChannel implements RealtimeChannel {
         before?: string;
         after?: string;
     }): Promise<RealtimeMessage[]>;
+    /**
+     * Ensure WebSocket connection is established and ready
+     */
+    private ensureConnected;
+    /**
+     * Send a message, queuing if socket not ready
+     */
+    private sendMessage;
+    /**
+     * Send a queued message and set up response handling
+     */
+    private sendQueuedMessage;
+    /**
+     * Flush all queued messages when connection becomes ready
+     */
+    private flushMessageQueue;
     private connectWebSocket;
+    /**
+     * Reject all queued messages with the given error
+     */
+    private rejectQueuedMessages;
     private handleWebSocketMessage;
     private startHeartbeat;
     private scheduleReconnect;

package/dist/index.js

@@ -2751,40 +2751,73 @@ var BlinkRealtimeChannel = class {
   presenceCallbacks = [];
   websocket = null;
   isSubscribed = false;
+  isConnected = false;
+  isConnecting = false;
   reconnectTimer = null;
   heartbeatTimer = null;
   reconnectAttempts = 0;
+  // Message queuing for when socket is not ready
+  messageQueue = [];
+  pendingSubscription = null;
+  // Connection promise for awaiting readiness
+  connectionPromise = null;
+  /**
+   * Check if channel is ready for publishing
+   */
+  isReady() {
+    return this.isConnected && this.isSubscribed;
+  }
   async subscribe(options = {}) {
     if (this.isSubscribed) {
       return;
     }
-    try {
-      await this.connectWebSocket();
-      if (this.websocket) {
-        const subscribeMessage = {
-          type: "subscribe",
-          payload: {
-            channel: this.channelName,
-            userId: options.userId,
-            metadata: options.metadata
-          }
-        };
-        this.websocket.send(JSON.stringify(subscribeMessage));
-        this.isSubscribed = true;
-        this.startHeartbeat();
+    await this.ensureConnected();
+    return new Promise((resolve, reject) => {
+      if (this.pendingSubscription) {
+        clearTimeout(this.pendingSubscription.timeout);
+        this.pendingSubscription.reject(new BlinkRealtimeError("Subscription cancelled by new subscription request"));
       }
-    } catch (error) {
-      console.error("WebSocket subscription error:", error);
-      throw new BlinkRealtimeError(
-        `Failed to subscribe to channel ${this.channelName}: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
-    }
+      const timeout = setTimeout(() => {
+        this.pendingSubscription = null;
+        reject(new BlinkRealtimeError("Subscription timeout - no acknowledgment from server"));
+      }, 1e4);
+      this.pendingSubscription = {
+        options,
+        resolve: () => {
+          clearTimeout(timeout);
+          this.pendingSubscription = null;
+          this.isSubscribed = true;
+          this.startHeartbeat();
+          resolve();
+        },
+        reject: (error) => {
+          clearTimeout(timeout);
+          this.pendingSubscription = null;
+          reject(error);
+        },
+        timeout
+      };
+      const subscribeMessage = {
+        type: "subscribe",
+        payload: {
+          channel: this.channelName,
+          userId: options.userId,
+          metadata: options.metadata
+        }
+      };
+      this.websocket.send(JSON.stringify(subscribeMessage));
+    });
   }
   async unsubscribe() {
     if (!this.isSubscribed) {
       return;
     }
-    if (this.websocket) {
+    if (this.pendingSubscription) {
+      clearTimeout(this.pendingSubscription.timeout);
+      this.pendingSubscription.reject(new BlinkRealtimeError("Subscription cancelled by unsubscribe"));
+      this.pendingSubscription = null;
+    }
+    if (this.websocket && this.websocket.readyState === 1) {
       const unsubscribeMessage = {
         type: "unsubscribe",
         payload: {
@@ -2796,42 +2829,18 @@ var BlinkRealtimeChannel = class {
     this.cleanup();
   }
   async publish(type, data, options = {}) {
-    if (!this.websocket || this.websocket.readyState !== 1) {
-      throw new BlinkRealtimeError("Not connected to realtime channel. Call subscribe() first.");
-    }
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        this.websocket.removeEventListener("message", handleResponse);
-        reject(new BlinkRealtimeError("Publish timeout - no response from server"));
-      }, 5e3);
-      const handleResponse = (event) => {
-        try {
-          const message = JSON.parse(event.data);
-          if (message.type === "published" && message.payload.channel === this.channelName) {
-            clearTimeout(timeout);
-            this.websocket.removeEventListener("message", handleResponse);
-            resolve(message.payload.messageId);
-          } else if (message.type === "error") {
-            clearTimeout(timeout);
-            this.websocket.removeEventListener("message", handleResponse);
-            reject(new BlinkRealtimeError(`Server error: ${message.payload.error}`));
-          }
-        } catch (err) {
-        }
-      };
-      this.websocket.addEventListener("message", handleResponse);
-      const publishMessage = {
-        type: "publish",
-        payload: {
-          channel: this.channelName,
-          type,
-          data,
-          userId: options.userId,
-          metadata: options.metadata
-        }
-      };
-      this.websocket.send(JSON.stringify(publishMessage));
-    });
+    await this.ensureConnected();
+    const publishMessage = {
+      type: "publish",
+      payload: {
+        channel: this.channelName,
+        type,
+        data,
+        userId: options.userId,
+        metadata: options.metadata
+      }
+    };
+    return this.sendMessage(JSON.stringify(publishMessage));
   }
   onMessage(callback) {
     this.messageCallbacks.push(callback);
@@ -2878,10 +2887,105 @@ var BlinkRealtimeChannel = class {
       );
     }
   }
+  /**
+   * Ensure WebSocket connection is established and ready
+   */
+  async ensureConnected() {
+    if (this.isConnected && this.websocket?.readyState === 1) {
+      return;
+    }
+    if (this.connectionPromise) {
+      return this.connectionPromise;
+    }
+    this.connectionPromise = this.connectWebSocket();
+    try {
+      await this.connectionPromise;
+    } finally {
+      this.connectionPromise = null;
+    }
+  }
+  /**
+   * Send a message, queuing if socket not ready
+   */
+  sendMessage(message) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        const index = this.messageQueue.findIndex((q) => q.resolve === resolve);
+        if (index > -1) {
+          this.messageQueue.splice(index, 1);
+        }
+        reject(new BlinkRealtimeError("Message send timeout - no response from server"));
+      }, 1e4);
+      const queuedMessage = {
+        message,
+        resolve,
+        reject,
+        timeout
+      };
+      if (this.websocket && this.websocket.readyState === 1) {
+        this.sendQueuedMessage(queuedMessage);
+      } else {
+        this.messageQueue.push(queuedMessage);
+      }
+    });
+  }
+  /**
+   * Send a queued message and set up response handling
+   */
+  sendQueuedMessage(queuedMessage) {
+    const { message, resolve, reject, timeout } = queuedMessage;
+    const handleResponse = (event) => {
+      try {
+        const response = JSON.parse(event.data);
+        if (response.type === "published" && response.payload.channel === this.channelName) {
+          clearTimeout(timeout);
+          this.websocket.removeEventListener("message", handleResponse);
+          resolve(response.payload.messageId);
+        } else if (response.type === "error") {
+          clearTimeout(timeout);
+          this.websocket.removeEventListener("message", handleResponse);
+          reject(new BlinkRealtimeError(`Server error: ${response.payload.error}`));
+        }
+      } catch (err) {
+      }
+    };
+    this.websocket.addEventListener("message", handleResponse);
+    this.websocket.send(message);
+  }
+  /**
+   * Flush all queued messages when connection becomes ready
+   */
+  flushMessageQueue() {
+    if (!this.websocket || this.websocket.readyState !== 1) {
+      return;
+    }
+    const queue = [...this.messageQueue];
+    this.messageQueue = [];
+    queue.forEach((queuedMessage) => {
+      this.sendQueuedMessage(queuedMessage);
+    });
+  }
   async connectWebSocket() {
     if (this.websocket && this.websocket.readyState === 1) {
+      this.isConnected = true;
       return;
     }
+    if (this.isConnecting) {
+      return new Promise((resolve, reject) => {
+        const checkConnection = () => {
+          if (this.isConnected) {
+            resolve();
+          } else if (!this.isConnecting) {
+            reject(new BlinkRealtimeError("Connection failed"));
+          } else {
+            setTimeout(checkConnection, 100);
+          }
+        };
+        checkConnection();
+      });
+    }
+    this.isConnecting = true;
+    this.isConnected = false;
     return new Promise((resolve, reject) => {
       try {
         const httpClient = this.httpClient;
@@ -2892,12 +2996,16 @@ var BlinkRealtimeChannel = class {
         const WSClass = getWebSocketClass();
         this.websocket = new WSClass(wsUrl);
         if (!this.websocket) {
+          this.isConnecting = false;
           reject(new BlinkRealtimeError("Failed to create WebSocket instance"));
           return;
         }
         this.websocket.onopen = () => {
           console.log(`\u{1F517} Connected to realtime for project ${this.projectId}`);
+          this.isConnecting = false;
+          this.isConnected = true;
           this.reconnectAttempts = 0;
+          this.flushMessageQueue();
           resolve();
         };
         this.websocket.onmessage = (event) => {
@@ -2910,25 +3018,48 @@ var BlinkRealtimeChannel = class {
         };
         this.websocket.onclose = () => {
           console.log(`\u{1F50C} Disconnected from realtime for project ${this.projectId}`);
+          this.isConnecting = false;
+          this.isConnected = false;
           this.isSubscribed = false;
+          this.rejectQueuedMessages(new BlinkRealtimeError("WebSocket connection closed"));
+          if (this.pendingSubscription) {
+            clearTimeout(this.pendingSubscription.timeout);
+            this.pendingSubscription.reject(new BlinkRealtimeError("Connection closed during subscription"));
+            this.pendingSubscription = null;
+          }
           this.scheduleReconnect();
         };
         this.websocket.onerror = (error) => {
           console.error("WebSocket error:", error);
           console.error("WebSocket URL was:", wsUrl);
           console.error("WebSocket readyState:", this.websocket?.readyState);
+          this.isConnecting = false;
+          this.isConnected = false;
           reject(new BlinkRealtimeError(`WebSocket connection failed to ${wsUrl}`));
         };
         setTimeout(() => {
           if (this.websocket?.readyState !== 1) {
+            this.isConnecting = false;
             reject(new BlinkRealtimeError("WebSocket connection timeout"));
           }
-        }, 5e3);
+        }, 1e4);
       } catch (error) {
+        this.isConnecting = false;
         reject(new BlinkRealtimeError(`Failed to create WebSocket connection: ${error instanceof Error ? error.message : "Unknown error"}`));
       }
     });
   }
+  /**
+   * Reject all queued messages with the given error
+   */
+  rejectQueuedMessages(error) {
+    const queue = [...this.messageQueue];
+    this.messageQueue = [];
+    queue.forEach((queuedMessage) => {
+      clearTimeout(queuedMessage.timeout);
+      queuedMessage.reject(error);
+    });
+  }
   handleWebSocketMessage(message) {
     switch (message.type) {
       case "message":
@@ -2952,6 +3083,9 @@ var BlinkRealtimeChannel = class {
         break;
       case "subscribed":
         console.log(`\u2705 Subscribed to channel: ${message.payload.channel}`);
+        if (this.pendingSubscription && message.payload.channel === this.channelName) {
+          this.pendingSubscription.resolve();
+        }
         break;
       case "unsubscribed":
         console.log(`\u274C Unsubscribed from channel: ${message.payload.channel}`);
@@ -2962,6 +3096,9 @@ var BlinkRealtimeChannel = class {
         break;
       case "error":
         console.error("Realtime error:", message.payload.error);
+        if (this.pendingSubscription && message.payload.channel === this.channelName) {
+          this.pendingSubscription.reject(new BlinkRealtimeError(`Subscription error: ${message.payload.error}`));
+        }
         break;
       default:
         console.log("Unknown message type:", message.type);
@@ -2981,16 +3118,19 @@ var BlinkRealtimeChannel = class {
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
     }
+    if (!this.isSubscribed && !this.pendingSubscription) {
+      return;
+    }
     this.reconnectAttempts++;
     const baseDelay = Math.min(3e4, Math.pow(2, this.reconnectAttempts) * 1e3);
     const jitter = Math.random() * 1e3;
     const delay = baseDelay + jitter;
     console.log(`\u{1F504} Scheduling reconnect attempt ${this.reconnectAttempts} in ${Math.round(delay)}ms`);
     this.reconnectTimer = globalThis.setTimeout(async () => {
-      if (this.isSubscribed) {
+      if (this.isSubscribed || this.pendingSubscription) {
         try {
           await this.connectWebSocket();
-          if (this.websocket) {
+          if (this.isSubscribed && this.websocket) {
             const subscribeMessage = {
               type: "subscribe",
               payload: {
@@ -3009,6 +3149,14 @@ var BlinkRealtimeChannel = class {
   }
   cleanup() {
     this.isSubscribed = false;
+    this.isConnected = false;
+    this.isConnecting = false;
+    if (this.pendingSubscription) {
+      clearTimeout(this.pendingSubscription.timeout);
+      this.pendingSubscription.reject(new BlinkRealtimeError("Channel cleanup"));
+      this.pendingSubscription = null;
+    }
+    this.rejectQueuedMessages(new BlinkRealtimeError("Channel cleanup"));
     if (this.heartbeatTimer) {
       clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = null;

package/dist/index.mjs

@@ -2749,40 +2749,73 @@ var BlinkRealtimeChannel = class {
   presenceCallbacks = [];
   websocket = null;
   isSubscribed = false;
+  isConnected = false;
+  isConnecting = false;
   reconnectTimer = null;
   heartbeatTimer = null;
   reconnectAttempts = 0;
+  // Message queuing for when socket is not ready
+  messageQueue = [];
+  pendingSubscription = null;
+  // Connection promise for awaiting readiness
+  connectionPromise = null;
+  /**
+   * Check if channel is ready for publishing
+   */
+  isReady() {
+    return this.isConnected && this.isSubscribed;
+  }
   async subscribe(options = {}) {
     if (this.isSubscribed) {
       return;
     }
-    try {
-      await this.connectWebSocket();
-      if (this.websocket) {
-        const subscribeMessage = {
-          type: "subscribe",
-          payload: {
-            channel: this.channelName,
-            userId: options.userId,
-            metadata: options.metadata
-          }
-        };
-        this.websocket.send(JSON.stringify(subscribeMessage));
-        this.isSubscribed = true;
-        this.startHeartbeat();
+    await this.ensureConnected();
+    return new Promise((resolve, reject) => {
+      if (this.pendingSubscription) {
+        clearTimeout(this.pendingSubscription.timeout);
+        this.pendingSubscription.reject(new BlinkRealtimeError("Subscription cancelled by new subscription request"));
       }
-    } catch (error) {
-      console.error("WebSocket subscription error:", error);
-      throw new BlinkRealtimeError(
-        `Failed to subscribe to channel ${this.channelName}: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
-    }
+      const timeout = setTimeout(() => {
+        this.pendingSubscription = null;
+        reject(new BlinkRealtimeError("Subscription timeout - no acknowledgment from server"));
+      }, 1e4);
+      this.pendingSubscription = {
+        options,
+        resolve: () => {
+          clearTimeout(timeout);
+          this.pendingSubscription = null;
+          this.isSubscribed = true;
+          this.startHeartbeat();
+          resolve();
+        },
+        reject: (error) => {
+          clearTimeout(timeout);
+          this.pendingSubscription = null;
+          reject(error);
+        },
+        timeout
+      };
+      const subscribeMessage = {
+        type: "subscribe",
+        payload: {
+          channel: this.channelName,
+          userId: options.userId,
+          metadata: options.metadata
+        }
+      };
+      this.websocket.send(JSON.stringify(subscribeMessage));
+    });
   }
   async unsubscribe() {
     if (!this.isSubscribed) {
       return;
     }
-    if (this.websocket) {
+    if (this.pendingSubscription) {
+      clearTimeout(this.pendingSubscription.timeout);
+      this.pendingSubscription.reject(new BlinkRealtimeError("Subscription cancelled by unsubscribe"));
+      this.pendingSubscription = null;
+    }
+    if (this.websocket && this.websocket.readyState === 1) {
       const unsubscribeMessage = {
         type: "unsubscribe",
         payload: {
@@ -2794,42 +2827,18 @@ var BlinkRealtimeChannel = class {
     this.cleanup();
   }
   async publish(type, data, options = {}) {
-    if (!this.websocket || this.websocket.readyState !== 1) {
-      throw new BlinkRealtimeError("Not connected to realtime channel. Call subscribe() first.");
-    }
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        this.websocket.removeEventListener("message", handleResponse);
-        reject(new BlinkRealtimeError("Publish timeout - no response from server"));
-      }, 5e3);
-      const handleResponse = (event) => {
-        try {
-          const message = JSON.parse(event.data);
-          if (message.type === "published" && message.payload.channel === this.channelName) {
-            clearTimeout(timeout);
-            this.websocket.removeEventListener("message", handleResponse);
-            resolve(message.payload.messageId);
-          } else if (message.type === "error") {
-            clearTimeout(timeout);
-            this.websocket.removeEventListener("message", handleResponse);
-            reject(new BlinkRealtimeError(`Server error: ${message.payload.error}`));
-          }
-        } catch (err) {
-        }
-      };
-      this.websocket.addEventListener("message", handleResponse);
-      const publishMessage = {
-        type: "publish",
-        payload: {
-          channel: this.channelName,
-          type,
-          data,
-          userId: options.userId,
-          metadata: options.metadata
-        }
-      };
-      this.websocket.send(JSON.stringify(publishMessage));
-    });
+    await this.ensureConnected();
+    const publishMessage = {
+      type: "publish",
+      payload: {
+        channel: this.channelName,
+        type,
+        data,
+        userId: options.userId,
+        metadata: options.metadata
+      }
+    };
+    return this.sendMessage(JSON.stringify(publishMessage));
   }
   onMessage(callback) {
     this.messageCallbacks.push(callback);
@@ -2876,10 +2885,105 @@ var BlinkRealtimeChannel = class {
       );
     }
   }
+  /**
+   * Ensure WebSocket connection is established and ready
+   */
+  async ensureConnected() {
+    if (this.isConnected && this.websocket?.readyState === 1) {
+      return;
+    }
+    if (this.connectionPromise) {
+      return this.connectionPromise;
+    }
+    this.connectionPromise = this.connectWebSocket();
+    try {
+      await this.connectionPromise;
+    } finally {
+      this.connectionPromise = null;
+    }
+  }
+  /**
+   * Send a message, queuing if socket not ready
+   */
+  sendMessage(message) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        const index = this.messageQueue.findIndex((q) => q.resolve === resolve);
+        if (index > -1) {
+          this.messageQueue.splice(index, 1);
+        }
+        reject(new BlinkRealtimeError("Message send timeout - no response from server"));
+      }, 1e4);
+      const queuedMessage = {
+        message,
+        resolve,
+        reject,
+        timeout
+      };
+      if (this.websocket && this.websocket.readyState === 1) {
+        this.sendQueuedMessage(queuedMessage);
+      } else {
+        this.messageQueue.push(queuedMessage);
+      }
+    });
+  }
+  /**
+   * Send a queued message and set up response handling
+   */
+  sendQueuedMessage(queuedMessage) {
+    const { message, resolve, reject, timeout } = queuedMessage;
+    const handleResponse = (event) => {
+      try {
+        const response = JSON.parse(event.data);
+        if (response.type === "published" && response.payload.channel === this.channelName) {
+          clearTimeout(timeout);
+          this.websocket.removeEventListener("message", handleResponse);
+          resolve(response.payload.messageId);
+        } else if (response.type === "error") {
+          clearTimeout(timeout);
+          this.websocket.removeEventListener("message", handleResponse);
+          reject(new BlinkRealtimeError(`Server error: ${response.payload.error}`));
+        }
+      } catch (err) {
+      }
+    };
+    this.websocket.addEventListener("message", handleResponse);
+    this.websocket.send(message);
+  }
+  /**
+   * Flush all queued messages when connection becomes ready
+   */
+  flushMessageQueue() {
+    if (!this.websocket || this.websocket.readyState !== 1) {
+      return;
+    }
+    const queue = [...this.messageQueue];
+    this.messageQueue = [];
+    queue.forEach((queuedMessage) => {
+      this.sendQueuedMessage(queuedMessage);
+    });
+  }
   async connectWebSocket() {
     if (this.websocket && this.websocket.readyState === 1) {
+      this.isConnected = true;
       return;
     }
+    if (this.isConnecting) {
+      return new Promise((resolve, reject) => {
+        const checkConnection = () => {
+          if (this.isConnected) {
+            resolve();
+          } else if (!this.isConnecting) {
+            reject(new BlinkRealtimeError("Connection failed"));
+          } else {
+            setTimeout(checkConnection, 100);
+          }
+        };
+        checkConnection();
+      });
+    }
+    this.isConnecting = true;
+    this.isConnected = false;
     return new Promise((resolve, reject) => {
       try {
         const httpClient = this.httpClient;
@@ -2890,12 +2994,16 @@ var BlinkRealtimeChannel = class {
         const WSClass = getWebSocketClass();
         this.websocket = new WSClass(wsUrl);
         if (!this.websocket) {
+          this.isConnecting = false;
           reject(new BlinkRealtimeError("Failed to create WebSocket instance"));
           return;
         }
         this.websocket.onopen = () => {
           console.log(`\u{1F517} Connected to realtime for project ${this.projectId}`);
+          this.isConnecting = false;
+          this.isConnected = true;
           this.reconnectAttempts = 0;
+          this.flushMessageQueue();
           resolve();
         };
         this.websocket.onmessage = (event) => {
@@ -2908,25 +3016,48 @@ var BlinkRealtimeChannel = class {
         };
         this.websocket.onclose = () => {
           console.log(`\u{1F50C} Disconnected from realtime for project ${this.projectId}`);
+          this.isConnecting = false;
+          this.isConnected = false;
           this.isSubscribed = false;
+          this.rejectQueuedMessages(new BlinkRealtimeError("WebSocket connection closed"));
+          if (this.pendingSubscription) {
+            clearTimeout(this.pendingSubscription.timeout);
+            this.pendingSubscription.reject(new BlinkRealtimeError("Connection closed during subscription"));
+            this.pendingSubscription = null;
+          }
           this.scheduleReconnect();
         };
         this.websocket.onerror = (error) => {
           console.error("WebSocket error:", error);
           console.error("WebSocket URL was:", wsUrl);
           console.error("WebSocket readyState:", this.websocket?.readyState);
+          this.isConnecting = false;
+          this.isConnected = false;
           reject(new BlinkRealtimeError(`WebSocket connection failed to ${wsUrl}`));
         };
         setTimeout(() => {
           if (this.websocket?.readyState !== 1) {
+            this.isConnecting = false;
             reject(new BlinkRealtimeError("WebSocket connection timeout"));
           }
-        }, 5e3);
+        }, 1e4);
       } catch (error) {
+        this.isConnecting = false;
         reject(new BlinkRealtimeError(`Failed to create WebSocket connection: ${error instanceof Error ? error.message : "Unknown error"}`));
       }
     });
   }
+  /**
+   * Reject all queued messages with the given error
+   */
+  rejectQueuedMessages(error) {
+    const queue = [...this.messageQueue];
+    this.messageQueue = [];
+    queue.forEach((queuedMessage) => {
+      clearTimeout(queuedMessage.timeout);
+      queuedMessage.reject(error);
+    });
+  }
   handleWebSocketMessage(message) {
     switch (message.type) {
       case "message":
@@ -2950,6 +3081,9 @@ var BlinkRealtimeChannel = class {
         break;
       case "subscribed":
         console.log(`\u2705 Subscribed to channel: ${message.payload.channel}`);
+        if (this.pendingSubscription && message.payload.channel === this.channelName) {
+          this.pendingSubscription.resolve();
+        }
         break;
       case "unsubscribed":
         console.log(`\u274C Unsubscribed from channel: ${message.payload.channel}`);
@@ -2960,6 +3094,9 @@ var BlinkRealtimeChannel = class {
         break;
       case "error":
         console.error("Realtime error:", message.payload.error);
+        if (this.pendingSubscription && message.payload.channel === this.channelName) {
+          this.pendingSubscription.reject(new BlinkRealtimeError(`Subscription error: ${message.payload.error}`));
+        }
         break;
       default:
         console.log("Unknown message type:", message.type);
@@ -2979,16 +3116,19 @@ var BlinkRealtimeChannel = class {
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
     }
+    if (!this.isSubscribed && !this.pendingSubscription) {
+      return;
+    }
     this.reconnectAttempts++;
     const baseDelay = Math.min(3e4, Math.pow(2, this.reconnectAttempts) * 1e3);
     const jitter = Math.random() * 1e3;
     const delay = baseDelay + jitter;
     console.log(`\u{1F504} Scheduling reconnect attempt ${this.reconnectAttempts} in ${Math.round(delay)}ms`);
     this.reconnectTimer = globalThis.setTimeout(async () => {
-      if (this.isSubscribed) {
+      if (this.isSubscribed || this.pendingSubscription) {
         try {
           await this.connectWebSocket();
-          if (this.websocket) {
+          if (this.isSubscribed && this.websocket) {
             const subscribeMessage = {
               type: "subscribe",
               payload: {
@@ -3007,6 +3147,14 @@ var BlinkRealtimeChannel = class {
   }
   cleanup() {
     this.isSubscribed = false;
+    this.isConnected = false;
+    this.isConnecting = false;
+    if (this.pendingSubscription) {
+      clearTimeout(this.pendingSubscription.timeout);
+      this.pendingSubscription.reject(new BlinkRealtimeError("Channel cleanup"));
+      this.pendingSubscription = null;
+    }
+    this.rejectQueuedMessages(new BlinkRealtimeError("Channel cleanup"));
     if (this.heartbeatTimer) {
       clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = null;

package/package.json

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