@blinkdotnew/sdk 0.5.1 → 0.6.1

package/README.md

@@ -64,6 +64,16 @@ const response = await blink.data.fetch({
   body: { /* email data */ }
 })
 
+// Realtime operations (live messaging and presence)
+const unsubscribe = await blink.realtime.subscribe('chat-room', (message) => {
+  console.log('New message:', message.data)
+})
+
+await blink.realtime.publish('chat-room', 'message', { text: 'Hello world!' })
+
+const users = await blink.realtime.presence('chat-room')
+console.log('Online users:', users.length)
+
 // Storage operations (instant - returns public URL directly)
 const { publicUrl } = await blink.storage.upload(
   file,
@@ -90,6 +100,7 @@ This SDK powers every Blink-generated app with:
 - **🤖 AI**: Text generation with web search, object generation, image creation, 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
+- **⚡ Realtime**: WebSocket-based pub/sub messaging, presence tracking, and live updates
 - **🌐 Universal**: Works on client-side and server-side
 - **📱 Framework Agnostic**: React, Vue, Svelte, vanilla JS, Node.js, Deno
 - **🔄 Real-time**: Built-in auth state management and token refresh
@@ -481,12 +492,150 @@ const { publicUrl } = await blink.storage.upload(
 await blink.storage.remove('file1.jpg', 'file2.jpg')
 ```
 
+### Realtime Operations
+
+```typescript
+// 🔥 Real-time Messaging & Presence (NEW!)
+// Perfect for chat apps, live collaboration, multiplayer games, and live updates
+
+// Simple subscribe and publish (most common pattern)
+const unsubscribe = await blink.realtime.subscribe('chat-room', (message) => {
+  console.log('New message:', message.data)
+  console.log('From user:', message.userId)
+  console.log('Message type:', message.type)
+})
+
+// Publish a message to all subscribers
+const messageId = await blink.realtime.publish('chat-room', 'message', {
+  text: 'Hello everyone!',
+  timestamp: Date.now()
+})
+
+// Advanced channel usage with presence tracking
+const channel = blink.realtime.channel('game-lobby')
+
+// Subscribe with user metadata
+await channel.subscribe({
+  userId: user.id,
+  metadata: { 
+    displayName: user.name,
+    avatar: user.avatar,
+    status: 'online'
+  }
+})
+
+// Listen for messages
+const unsubMessage = channel.onMessage((message) => {
+  if (message.type === 'chat') {
+    addChatMessage(message.data)
+  } else if (message.type === 'game-move') {
+    updateGameState(message.data)
+  }
+})
+
+// Listen for presence changes (who's online)
+const unsubPresence = channel.onPresence((users) => {
+  console.log(`${users.length} users online:`)
+  users.forEach(user => {
+    console.log(`- ${user.metadata?.displayName} (${user.userId})`)
+  })
+  updateOnlineUsersList(users)
+})
+
+// Publish different types of messages
+await channel.publish('chat', { text: 'Hello!' }, { userId: user.id })
+await channel.publish('game-move', { x: 5, y: 3, piece: 'king' })
+await channel.publish('typing', { isTyping: true })
+
+// Get current presence (one-time check)
+const currentUsers = await channel.getPresence()
+console.log('Currently online:', currentUsers.length)
+
+// Get message history
+const recentMessages = await channel.getMessages({ 
+  limit: 50,
+  before: lastMessageId // Pagination support
+})
+
+// Cleanup when done
+unsubMessage()
+unsubPresence()
+await channel.unsubscribe()
+
+// Or use the simple unsubscribe from subscribe()
+unsubscribe()
+
+// Multiple channels for different features
+const chatChannel = blink.realtime.channel('chat')
+const notificationChannel = blink.realtime.channel('notifications')
+const gameChannel = blink.realtime.channel('game-state')
+
+// Each channel is independent with its own subscribers and presence
+await chatChannel.subscribe({ userId: user.id })
+await notificationChannel.subscribe({ userId: user.id })
+await gameChannel.subscribe({ userId: user.id, metadata: { team: 'red' } })
+
+// Real-time collaboration example
+const docChannel = blink.realtime.channel(`document-${docId}`)
+
+await docChannel.subscribe({
+  userId: user.id,
+  metadata: { 
+    name: user.name,
+    cursor: { line: 1, column: 0 }
+  }
+})
+
+// Broadcast cursor movements
+docChannel.onMessage((message) => {
+  if (message.type === 'cursor-move') {
+    updateUserCursor(message.userId, message.data.position)
+  } else if (message.type === 'text-change') {
+    applyTextChange(message.data.delta)
+  }
+})
+
+// Send cursor updates
+await docChannel.publish('cursor-move', {
+  position: { line: 5, column: 10 }
+}, { userId: user.id })
+
+// Send text changes
+await docChannel.publish('text-change', {
+  delta: { insert: 'Hello', retain: 5 },
+  timestamp: Date.now()
+})
+
+// Presence with live cursor positions
+docChannel.onPresence((users) => {
+  users.forEach(user => {
+    if (user.metadata?.cursor) {
+      showUserCursor(user.userId, user.metadata.cursor)
+    }
+  })
+})
+
+// Auto-cleanup on page unload
+window.addEventListener('beforeunload', () => {
+  docChannel.unsubscribe()
+})
+
+// Error handling
+try {
+  await blink.realtime.publish('restricted-channel', 'message', { data: 'test' })
+} catch (error) {
+  if (error instanceof BlinkRealtimeError) {
+    console.error('Realtime error:', error.message)
+  }
+}
+```
+
 ## 🔧 Advanced Usage
 
 ### Error Handling
 
 ```typescript
-import { BlinkAuthError, BlinkAIError, BlinkStorageError, BlinkDataError } from '@blinkdotnew/sdk'
+import { BlinkAuthError, BlinkAIError, BlinkStorageError, BlinkDataError, BlinkRealtimeError } from '@blinkdotnew/sdk'
 
 try {
   const user = await blink.auth.me()
@@ -710,6 +859,130 @@ function EmailSender() {
     </div>
   )
 }
+
+// React example with realtime chat
+function RealtimeChat() {
+  const [messages, setMessages] = useState([])
+  const [newMessage, setNewMessage] = useState('')
+  const [onlineUsers, setOnlineUsers] = useState([])
+  const [user] = useState({ id: 'user123', name: 'John Doe' }) // From auth
+  
+  useEffect(() => {
+    const channel = blink.realtime.channel('chat-room')
+    
+    // Subscribe and listen for messages
+    const setupRealtime = async () => {
+      await channel.subscribe({
+        userId: user.id,
+        metadata: { displayName: user.name, avatar: '/avatar.png' }
+      })
+      
+      // Listen for new messages
+      channel.onMessage((message) => {
+        if (message.type === 'chat') {
+          setMessages(prev => [...prev, {
+            id: message.id,
+            text: message.data.text,
+            userId: message.userId,
+            timestamp: message.timestamp,
+            user: message.metadata?.displayName || 'Unknown'
+          }])
+        }
+      })
+      
+      // Listen for presence changes
+      channel.onPresence((users) => {
+        setOnlineUsers(users.map(u => ({
+          id: u.userId,
+          name: u.metadata?.displayName || 'Anonymous',
+          avatar: u.metadata?.avatar
+        })))
+      })
+      
+      // Load recent messages
+      const recentMessages = await channel.getMessages({ limit: 50 })
+      setMessages(recentMessages.map(msg => ({
+        id: msg.id,
+        text: msg.data.text,
+        userId: msg.userId,
+        timestamp: msg.timestamp,
+        user: msg.metadata?.displayName || 'Unknown'
+      })))
+    }
+    
+    setupRealtime()
+    
+    // Cleanup on unmount
+    return () => {
+      channel.unsubscribe()
+    }
+  }, [user.id, user.name])
+  
+  const sendMessage = async () => {
+    if (!newMessage.trim()) return
+    
+    try {
+      await blink.realtime.publish('chat-room', 'chat', {
+        text: newMessage,
+        timestamp: Date.now()
+      }, {
+        userId: user.id,
+        metadata: { displayName: user.name }
+      })
+      
+      setNewMessage('')
+    } catch (error) {
+      console.error('Failed to send message:', error)
+    }
+  }
+  
+  return (
+    <div style={{ display: 'flex', height: '400px' }}>
+      {/* Chat messages */}
+      <div style={{ flex: 1, padding: '1rem' }}>
+        <h3>Chat Room</h3>
+        <div style={{ height: '250px', overflowY: 'auto', border: '1px solid #ccc', padding: '0.5rem' }}>
+          {messages.map((msg) => (
+            <div key={msg.id} style={{ marginBottom: '0.5rem' }}>
+              <strong>{msg.user}:</strong> {msg.text}
+              <small style={{ color: '#666', marginLeft: '0.5rem' }}>
+                {new Date(msg.timestamp).toLocaleTimeString()}
+              </small>
+            </div>
+          ))}
+        </div>
+        
+        <div style={{ marginTop: '1rem', display: 'flex' }}>
+          <input
+            value={newMessage}
+            onChange={(e) => setNewMessage(e.target.value)}
+            placeholder="Type a message..."
+            style={{ flex: 1, marginRight: '0.5rem' }}
+            onKeyPress={(e) => e.key === 'Enter' && sendMessage()}
+          />
+          <button onClick={sendMessage}>Send</button>
+        </div>
+      </div>
+      
+      {/* Online users sidebar */}
+      <div style={{ width: '200px', borderLeft: '1px solid #ccc', padding: '1rem' }}>
+        <h4>Online ({onlineUsers.length})</h4>
+        {onlineUsers.map((user) => (
+          <div key={user.id} style={{ display: 'flex', alignItems: 'center', marginBottom: '0.5rem' }}>
+            <div style={{ 
+              width: '8px', 
+              height: '8px', 
+              backgroundColor: '#22c55e', 
+              borderRadius: '50%', 
+              marginRight: '0.5rem' 
+            }} />
+            {user.name}
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
 ```
 
 ### Next.js API Routes

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { BlinkClientConfig, BlinkUser, AuthState, HttpClient, TableOperations, CreateOptions, UpsertOptions, QueryOptions, ListResponse, UpdateOptions, FilterCondition, ScrapeResult, FetchRequest, FetchResponse, AsyncFetchResponse, SearchResponse, BlinkStorage, BlinkAI, StorageUploadOptions, StorageUploadResponse, TextGenerationRequest, TextGenerationResponse, ObjectGenerationRequest, ObjectGenerationResponse, ImageGenerationRequest, ImageGenerationResponse, SpeechGenerationRequest, SpeechGenerationResponse, TranscriptionRequest, TranscriptionResponse } from '@blink/core';
-export { AuthState, AuthTokens, BlinkAI, BlinkClientConfig, BlinkStorage, BlinkUser, CreateOptions, DataExtraction, FileObject, FilterCondition, ImageGenerationRequest, ImageGenerationResponse, ListResponse, Message, ObjectGenerationRequest, ObjectGenerationResponse, QueryOptions, SearchRequest, SearchResponse, SpeechGenerationRequest, SpeechGenerationResponse, StorageUploadOptions, StorageUploadResponse, TableOperations, TextGenerationRequest, TextGenerationResponse, TokenUsage, TranscriptionRequest, TranscriptionResponse, UpdateOptions, UpsertOptions } from '@blink/core';
+import { BlinkClientConfig, BlinkUser, AuthState, HttpClient, TableOperations, CreateOptions, UpsertOptions, QueryOptions, ListResponse, UpdateOptions, FilterCondition, ScrapeResult, FetchRequest, FetchResponse, AsyncFetchResponse, SearchResponse, BlinkStorage, BlinkAI, BlinkRealtime, StorageUploadOptions, StorageUploadResponse, TextGenerationRequest, TextGenerationResponse, ObjectGenerationRequest, ObjectGenerationResponse, ImageGenerationRequest, ImageGenerationResponse, SpeechGenerationRequest, SpeechGenerationResponse, TranscriptionRequest, TranscriptionResponse, RealtimeChannel, RealtimeMessage, RealtimeSubscribeOptions, RealtimePublishOptions, PresenceUser } from '@blink/core';
+export { AuthState, AuthTokens, BlinkAI, BlinkClientConfig, BlinkRealtime, BlinkRealtimeError, BlinkStorage, BlinkUser, CreateOptions, DataExtraction, FileObject, FilterCondition, ImageGenerationRequest, ImageGenerationResponse, ListResponse, Message, ObjectGenerationRequest, ObjectGenerationResponse, PresenceUser, QueryOptions, RealtimeChannel, RealtimeGetMessagesOptions, RealtimeMessage, RealtimePublishOptions, RealtimeSubscribeOptions, SearchRequest, SearchResponse, SpeechGenerationRequest, SpeechGenerationResponse, StorageUploadOptions, StorageUploadResponse, TableOperations, TextGenerationRequest, TextGenerationResponse, TokenUsage, TranscriptionRequest, TranscriptionResponse, UpdateOptions, UpsertOptions } from '@blink/core';
 
 /**
  * Blink Auth Module - Client-side authentication management
@@ -259,6 +259,7 @@ interface BlinkClient {
     storage: BlinkStorage;
     ai: BlinkAI;
     data: BlinkData;
+    realtime: BlinkRealtime;
 }
 /**
  * Create a new Blink client instance
@@ -665,4 +666,57 @@ declare class BlinkAIImpl implements BlinkAI {
     transcribeAudio(options: TranscriptionRequest): Promise<TranscriptionResponse>;
 }
 
-export { type AuthStateChangeCallback, BlinkAIImpl, type BlinkClient, type BlinkData, BlinkDataImpl, BlinkDatabase, BlinkStorageImpl, BlinkTable, createClient };
+/**
+ * Blink Realtime Module - Real-time messaging and presence
+ * Provides pub/sub messaging, presence tracking, and live updates
+ */
+
+declare class BlinkRealtimeChannel implements RealtimeChannel {
+    private channelName;
+    private httpClient;
+    private projectId;
+    private messageCallbacks;
+    private presenceCallbacks;
+    private websocket;
+    private isSubscribed;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private reconnectAttempts;
+    constructor(channelName: string, httpClient: HttpClient, projectId: string);
+    subscribe(options?: {
+        userId?: string;
+        metadata?: Record<string, any>;
+    }): Promise<void>;
+    unsubscribe(): Promise<void>;
+    publish(type: string, data: any, options?: {
+        userId?: string;
+        metadata?: Record<string, any>;
+    }): Promise<string>;
+    onMessage(callback: (message: RealtimeMessage) => void): () => void;
+    onPresence(callback: (users: PresenceUser[]) => void): () => void;
+    getPresence(): Promise<PresenceUser[]>;
+    getMessages(options?: {
+        limit?: number;
+        before?: string;
+        after?: string;
+    }): Promise<RealtimeMessage[]>;
+    private connectWebSocket;
+    private handleWebSocketMessage;
+    private startHeartbeat;
+    private scheduleReconnect;
+    private cleanup;
+}
+declare class BlinkRealtimeImpl implements BlinkRealtime {
+    private httpClient;
+    private projectId;
+    private channels;
+    private handlers;
+    constructor(httpClient: HttpClient, projectId: string);
+    channel(name: string): RealtimeChannel;
+    subscribe(channelName: string, callback: (message: RealtimeMessage) => void, options?: RealtimeSubscribeOptions): Promise<() => void>;
+    publish(channelName: string, type: string, data: any, options?: RealtimePublishOptions): Promise<string>;
+    presence(channelName: string): Promise<PresenceUser[]>;
+    onPresence(channelName: string, callback: (users: PresenceUser[]) => void): () => void;
+}
+
+export { type AuthStateChangeCallback, BlinkAIImpl, type BlinkClient, type BlinkData, BlinkDataImpl, BlinkDatabase, BlinkRealtimeChannel, BlinkRealtimeImpl, BlinkStorageImpl, BlinkTable, createClient };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { BlinkClientConfig, BlinkUser, AuthState, HttpClient, TableOperations, CreateOptions, UpsertOptions, QueryOptions, ListResponse, UpdateOptions, FilterCondition, ScrapeResult, FetchRequest, FetchResponse, AsyncFetchResponse, SearchResponse, BlinkStorage, BlinkAI, StorageUploadOptions, StorageUploadResponse, TextGenerationRequest, TextGenerationResponse, ObjectGenerationRequest, ObjectGenerationResponse, ImageGenerationRequest, ImageGenerationResponse, SpeechGenerationRequest, SpeechGenerationResponse, TranscriptionRequest, TranscriptionResponse } from '@blink/core';
-export { AuthState, AuthTokens, BlinkAI, BlinkClientConfig, BlinkStorage, BlinkUser, CreateOptions, DataExtraction, FileObject, FilterCondition, ImageGenerationRequest, ImageGenerationResponse, ListResponse, Message, ObjectGenerationRequest, ObjectGenerationResponse, QueryOptions, SearchRequest, SearchResponse, SpeechGenerationRequest, SpeechGenerationResponse, StorageUploadOptions, StorageUploadResponse, TableOperations, TextGenerationRequest, TextGenerationResponse, TokenUsage, TranscriptionRequest, TranscriptionResponse, UpdateOptions, UpsertOptions } from '@blink/core';
+import { BlinkClientConfig, BlinkUser, AuthState, HttpClient, TableOperations, CreateOptions, UpsertOptions, QueryOptions, ListResponse, UpdateOptions, FilterCondition, ScrapeResult, FetchRequest, FetchResponse, AsyncFetchResponse, SearchResponse, BlinkStorage, BlinkAI, BlinkRealtime, StorageUploadOptions, StorageUploadResponse, TextGenerationRequest, TextGenerationResponse, ObjectGenerationRequest, ObjectGenerationResponse, ImageGenerationRequest, ImageGenerationResponse, SpeechGenerationRequest, SpeechGenerationResponse, TranscriptionRequest, TranscriptionResponse, RealtimeChannel, RealtimeMessage, RealtimeSubscribeOptions, RealtimePublishOptions, PresenceUser } from '@blink/core';
+export { AuthState, AuthTokens, BlinkAI, BlinkClientConfig, BlinkRealtime, BlinkRealtimeError, BlinkStorage, BlinkUser, CreateOptions, DataExtraction, FileObject, FilterCondition, ImageGenerationRequest, ImageGenerationResponse, ListResponse, Message, ObjectGenerationRequest, ObjectGenerationResponse, PresenceUser, QueryOptions, RealtimeChannel, RealtimeGetMessagesOptions, RealtimeMessage, RealtimePublishOptions, RealtimeSubscribeOptions, SearchRequest, SearchResponse, SpeechGenerationRequest, SpeechGenerationResponse, StorageUploadOptions, StorageUploadResponse, TableOperations, TextGenerationRequest, TextGenerationResponse, TokenUsage, TranscriptionRequest, TranscriptionResponse, UpdateOptions, UpsertOptions } from '@blink/core';
 
 /**
  * Blink Auth Module - Client-side authentication management
@@ -259,6 +259,7 @@ interface BlinkClient {
     storage: BlinkStorage;
     ai: BlinkAI;
     data: BlinkData;
+    realtime: BlinkRealtime;
 }
 /**
  * Create a new Blink client instance
@@ -665,4 +666,57 @@ declare class BlinkAIImpl implements BlinkAI {
     transcribeAudio(options: TranscriptionRequest): Promise<TranscriptionResponse>;
 }
 
-export { type AuthStateChangeCallback, BlinkAIImpl, type BlinkClient, type BlinkData, BlinkDataImpl, BlinkDatabase, BlinkStorageImpl, BlinkTable, createClient };
+/**
+ * Blink Realtime Module - Real-time messaging and presence
+ * Provides pub/sub messaging, presence tracking, and live updates
+ */
+
+declare class BlinkRealtimeChannel implements RealtimeChannel {
+    private channelName;
+    private httpClient;
+    private projectId;
+    private messageCallbacks;
+    private presenceCallbacks;
+    private websocket;
+    private isSubscribed;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private reconnectAttempts;
+    constructor(channelName: string, httpClient: HttpClient, projectId: string);
+    subscribe(options?: {
+        userId?: string;
+        metadata?: Record<string, any>;
+    }): Promise<void>;
+    unsubscribe(): Promise<void>;
+    publish(type: string, data: any, options?: {
+        userId?: string;
+        metadata?: Record<string, any>;
+    }): Promise<string>;
+    onMessage(callback: (message: RealtimeMessage) => void): () => void;
+    onPresence(callback: (users: PresenceUser[]) => void): () => void;
+    getPresence(): Promise<PresenceUser[]>;
+    getMessages(options?: {
+        limit?: number;
+        before?: string;
+        after?: string;
+    }): Promise<RealtimeMessage[]>;
+    private connectWebSocket;
+    private handleWebSocketMessage;
+    private startHeartbeat;
+    private scheduleReconnect;
+    private cleanup;
+}
+declare class BlinkRealtimeImpl implements BlinkRealtime {
+    private httpClient;
+    private projectId;
+    private channels;
+    private handlers;
+    constructor(httpClient: HttpClient, projectId: string);
+    channel(name: string): RealtimeChannel;
+    subscribe(channelName: string, callback: (message: RealtimeMessage) => void, options?: RealtimeSubscribeOptions): Promise<() => void>;
+    publish(channelName: string, type: string, data: any, options?: RealtimePublishOptions): Promise<string>;
+    presence(channelName: string): Promise<PresenceUser[]>;
+    onPresence(channelName: string, callback: (users: PresenceUser[]) => void): () => void;
+}
+
+export { type AuthStateChangeCallback, BlinkAIImpl, type BlinkClient, type BlinkData, BlinkDataImpl, BlinkDatabase, BlinkRealtimeChannel, BlinkRealtimeImpl, BlinkStorageImpl, BlinkTable, createClient };

package/dist/index.js

@@ -1,5 +1,12 @@
 'use strict';
 
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
 // ../core/src/types.ts
 var BlinkError = class extends Error {
   constructor(message, code, status, details) {
@@ -46,6 +53,12 @@ var BlinkDataError = class extends BlinkError {
     this.name = "BlinkDataError";
   }
 };
+var BlinkRealtimeError = class extends BlinkError {
+  constructor(message, status, details) {
+    super(message, "REALTIME_ERROR", status, details);
+    this.name = "BlinkRealtimeError";
+  }
+};
 
 // ../core/src/query-builder.ts
 function buildFilterQuery(condition) {
@@ -576,6 +589,24 @@ var HttpClient = class {
   async dataSearch(projectId, request) {
     return this.post(`/api/data/${projectId}/search`, request);
   }
+  /**
+   * Realtime-specific requests
+   */
+  async realtimePublish(projectId, request) {
+    return this.post(`/api/realtime/${projectId}/publish`, request);
+  }
+  async realtimeGetPresence(projectId, channel) {
+    return this.get(`/api/realtime/${projectId}/presence`, { channel });
+  }
+  async realtimeGetMessages(projectId, options) {
+    const { channel, ...searchParams } = options;
+    return this.get(`/api/realtime/${projectId}/messages`, {
+      channel,
+      ...Object.fromEntries(
+        Object.entries(searchParams).map(([k, v]) => [k, String(v)])
+      )
+    });
+  }
   /**
    * Private helper methods
    */
@@ -2449,6 +2480,331 @@ var BlinkDataImpl = class {
   }
 };
 
+// src/realtime.ts
+var getWebSocketClass = () => {
+  if (typeof WebSocket !== "undefined") {
+    return WebSocket;
+  }
+  try {
+    const WS = __require("ws");
+    return WS;
+  } catch (error) {
+    throw new BlinkRealtimeError('WebSocket is not available. Install "ws" package for Node.js environments.');
+  }
+};
+var BlinkRealtimeChannel = class {
+  constructor(channelName, httpClient, projectId) {
+    this.channelName = channelName;
+    this.httpClient = httpClient;
+    this.projectId = projectId;
+  }
+  messageCallbacks = [];
+  presenceCallbacks = [];
+  websocket = null;
+  isSubscribed = false;
+  reconnectTimer = null;
+  heartbeatTimer = null;
+  reconnectAttempts = 0;
+  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();
+      }
+    } catch (error) {
+      throw new BlinkRealtimeError(
+        `Failed to subscribe to channel ${this.channelName}: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  async unsubscribe() {
+    if (!this.isSubscribed) {
+      return;
+    }
+    if (this.websocket) {
+      const unsubscribeMessage = {
+        type: "unsubscribe",
+        payload: {
+          channel: this.channelName
+        }
+      };
+      this.websocket.send(JSON.stringify(unsubscribeMessage));
+    }
+    this.cleanup();
+  }
+  async publish(type, data, options = {}) {
+    try {
+      const response = await this.httpClient.realtimePublish(this.projectId, {
+        channel: this.channelName,
+        type,
+        data,
+        userId: options.userId,
+        metadata: options.metadata
+      });
+      return response.data.messageId;
+    } catch (error) {
+      throw new BlinkRealtimeError(
+        `Failed to publish message to channel ${this.channelName}: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  onMessage(callback) {
+    this.messageCallbacks.push(callback);
+    return () => {
+      const index = this.messageCallbacks.indexOf(callback);
+      if (index > -1) {
+        this.messageCallbacks.splice(index, 1);
+      }
+    };
+  }
+  onPresence(callback) {
+    this.presenceCallbacks.push(callback);
+    return () => {
+      const index = this.presenceCallbacks.indexOf(callback);
+      if (index > -1) {
+        this.presenceCallbacks.splice(index, 1);
+      }
+    };
+  }
+  async getPresence() {
+    try {
+      const response = await this.httpClient.realtimeGetPresence(this.projectId, this.channelName);
+      return response.data.users;
+    } catch (error) {
+      throw new BlinkRealtimeError(
+        `Failed to get presence for channel ${this.channelName}: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  async getMessages(options = {}) {
+    try {
+      const response = await this.httpClient.realtimeGetMessages(this.projectId, {
+        channel: this.channelName,
+        limit: options.limit,
+        start: options.after,
+        // after = start from this ID onwards
+        end: options.before
+        // before = end at this ID
+      });
+      return response.data.messages;
+    } catch (error) {
+      throw new BlinkRealtimeError(
+        `Failed to get messages for channel ${this.channelName}: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  async connectWebSocket() {
+    if (this.websocket && this.websocket.readyState === 1) {
+      return;
+    }
+    return new Promise((resolve, reject) => {
+      try {
+        const baseUrl = this.httpClient.projectId.includes("localhost") ? "ws://localhost:3000" : "wss://core.blink.new";
+        const wsUrl = `${baseUrl}?project_id=${this.projectId}`;
+        const WSClass = getWebSocketClass();
+        this.websocket = new WSClass(wsUrl);
+        if (!this.websocket) {
+          reject(new BlinkRealtimeError("Failed to create WebSocket instance"));
+          return;
+        }
+        this.websocket.onopen = () => {
+          console.log(`\u{1F517} Connected to realtime for project ${this.projectId}`);
+          this.reconnectAttempts = 0;
+          resolve();
+        };
+        this.websocket.onmessage = (event) => {
+          try {
+            const message = JSON.parse(event.data);
+            this.handleWebSocketMessage(message);
+          } catch (error) {
+            console.error("Failed to parse WebSocket message:", error);
+          }
+        };
+        this.websocket.onclose = () => {
+          console.log(`\u{1F50C} Disconnected from realtime for project ${this.projectId}`);
+          this.isSubscribed = false;
+          this.scheduleReconnect();
+        };
+        this.websocket.onerror = (error) => {
+          console.error("WebSocket error:", error);
+          reject(new BlinkRealtimeError("WebSocket connection failed"));
+        };
+        setTimeout(() => {
+          if (this.websocket?.readyState !== 1) {
+            reject(new BlinkRealtimeError("WebSocket connection timeout"));
+          }
+        }, 5e3);
+      } catch (error) {
+        reject(new BlinkRealtimeError(`Failed to create WebSocket connection: ${error instanceof Error ? error.message : "Unknown error"}`));
+      }
+    });
+  }
+  handleWebSocketMessage(message) {
+    switch (message.type) {
+      case "message":
+        this.messageCallbacks.forEach((callback) => {
+          try {
+            callback(message.payload);
+          } catch (error) {
+            console.error("Error in message callback:", error);
+          }
+        });
+        break;
+      case "presence":
+        this.presenceCallbacks.forEach((callback) => {
+          try {
+            callback(message.payload.data || []);
+          } catch (error) {
+            console.error("Error in presence callback:", error);
+          }
+        });
+        break;
+      case "subscribed":
+        console.log(`\u2705 Subscribed to channel: ${message.payload.channel}`);
+        break;
+      case "unsubscribed":
+        console.log(`\u274C Unsubscribed from channel: ${message.payload.channel}`);
+        break;
+      case "pong":
+        break;
+      case "error":
+        console.error("Realtime error:", message.payload.error);
+        break;
+      default:
+        console.log("Unknown message type:", message.type);
+    }
+  }
+  startHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+    }
+    this.heartbeatTimer = globalThis.setInterval(() => {
+      if (this.websocket && this.websocket.readyState === 1) {
+        this.websocket.send(JSON.stringify({ type: "ping", payload: {} }));
+      }
+    }, 25e3);
+  }
+  scheduleReconnect() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+    }
+    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) {
+        try {
+          await this.connectWebSocket();
+          if (this.websocket) {
+            const subscribeMessage = {
+              type: "subscribe",
+              payload: {
+                channel: this.channelName
+              }
+            };
+            this.websocket.send(JSON.stringify(subscribeMessage));
+            this.startHeartbeat();
+          }
+        } catch (error) {
+          console.error("Reconnection failed:", error);
+          this.scheduleReconnect();
+        }
+      }
+    }, delay);
+  }
+  cleanup() {
+    this.isSubscribed = false;
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.websocket) {
+      this.websocket.close();
+      this.websocket = null;
+    }
+    this.messageCallbacks = [];
+    this.presenceCallbacks = [];
+  }
+};
+var BlinkRealtimeImpl = class {
+  constructor(httpClient, projectId) {
+    this.httpClient = httpClient;
+    this.projectId = projectId;
+  }
+  channels = /* @__PURE__ */ new Map();
+  handlers = {};
+  channel(name) {
+    if (!this.channels.has(name)) {
+      this.channels.set(name, new BlinkRealtimeChannel(name, this.httpClient, this.projectId));
+    }
+    return this.channels.get(name);
+  }
+  async subscribe(channelName, callback, options = {}) {
+    const channel = this.channel(channelName);
+    await channel.subscribe(options);
+    const state = this.handlers[channelName] ??= {
+      msgHandlers: /* @__PURE__ */ new Set(),
+      presHandlers: /* @__PURE__ */ new Set(),
+      subscribed: true
+    };
+    state.msgHandlers.add(callback);
+    const messageUnsub = channel.onMessage(callback);
+    return () => {
+      messageUnsub();
+      state.msgHandlers.delete(callback);
+      if (state.msgHandlers.size === 0 && state.presHandlers.size === 0) {
+        channel.unsubscribe();
+        delete this.handlers[channelName];
+      }
+    };
+  }
+  async publish(channelName, type, data, options = {}) {
+    const channel = this.channel(channelName);
+    return channel.publish(type, data, options);
+  }
+  async presence(channelName) {
+    const channel = this.channel(channelName);
+    return channel.getPresence();
+  }
+  onPresence(channelName, callback) {
+    const channel = this.channel(channelName);
+    const state = this.handlers[channelName] ??= {
+      msgHandlers: /* @__PURE__ */ new Set(),
+      presHandlers: /* @__PURE__ */ new Set(),
+      subscribed: false
+    };
+    state.presHandlers.add(callback);
+    const presenceUnsub = channel.onPresence(callback);
+    return () => {
+      presenceUnsub();
+      state.presHandlers.delete(callback);
+      if (state.msgHandlers.size === 0 && state.presHandlers.size === 0) {
+        channel.unsubscribe();
+        delete this.handlers[channelName];
+      }
+    };
+  }
+};
+
 // src/client.ts
 var BlinkClientImpl = class {
   auth;
@@ -2456,6 +2812,7 @@ var BlinkClientImpl = class {
   storage;
   ai;
   data;
+  realtime;
   httpClient;
   constructor(config) {
     this.auth = new BlinkAuth(config);
@@ -2468,6 +2825,7 @@ var BlinkClientImpl = class {
     this.storage = new BlinkStorageImpl(this.httpClient);
     this.ai = new BlinkAIImpl(this.httpClient);
     this.data = new BlinkDataImpl(this.httpClient, config.projectId);
+    this.realtime = new BlinkRealtimeImpl(this.httpClient, config.projectId);
   }
 };
 function createClient(config) {
@@ -2484,6 +2842,8 @@ function createClient(config) {
 exports.BlinkAIImpl = BlinkAIImpl;
 exports.BlinkDataImpl = BlinkDataImpl;
 exports.BlinkDatabase = BlinkDatabase;
+exports.BlinkRealtimeChannel = BlinkRealtimeChannel;
+exports.BlinkRealtimeImpl = BlinkRealtimeImpl;
 exports.BlinkStorageImpl = BlinkStorageImpl;
 exports.BlinkTable = BlinkTable;
 exports.createClient = createClient;

package/dist/index.mjs

@@ -1,3 +1,10 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
 // ../core/src/types.ts
 var BlinkError = class extends Error {
   constructor(message, code, status, details) {
@@ -44,6 +51,12 @@ var BlinkDataError = class extends BlinkError {
     this.name = "BlinkDataError";
   }
 };
+var BlinkRealtimeError = class extends BlinkError {
+  constructor(message, status, details) {
+    super(message, "REALTIME_ERROR", status, details);
+    this.name = "BlinkRealtimeError";
+  }
+};
 
 // ../core/src/query-builder.ts
 function buildFilterQuery(condition) {
@@ -574,6 +587,24 @@ var HttpClient = class {
   async dataSearch(projectId, request) {
     return this.post(`/api/data/${projectId}/search`, request);
   }
+  /**
+   * Realtime-specific requests
+   */
+  async realtimePublish(projectId, request) {
+    return this.post(`/api/realtime/${projectId}/publish`, request);
+  }
+  async realtimeGetPresence(projectId, channel) {
+    return this.get(`/api/realtime/${projectId}/presence`, { channel });
+  }
+  async realtimeGetMessages(projectId, options) {
+    const { channel, ...searchParams } = options;
+    return this.get(`/api/realtime/${projectId}/messages`, {
+      channel,
+      ...Object.fromEntries(
+        Object.entries(searchParams).map(([k, v]) => [k, String(v)])
+      )
+    });
+  }
   /**
    * Private helper methods
    */
@@ -2447,6 +2478,331 @@ var BlinkDataImpl = class {
   }
 };
 
+// src/realtime.ts
+var getWebSocketClass = () => {
+  if (typeof WebSocket !== "undefined") {
+    return WebSocket;
+  }
+  try {
+    const WS = __require("ws");
+    return WS;
+  } catch (error) {
+    throw new BlinkRealtimeError('WebSocket is not available. Install "ws" package for Node.js environments.');
+  }
+};
+var BlinkRealtimeChannel = class {
+  constructor(channelName, httpClient, projectId) {
+    this.channelName = channelName;
+    this.httpClient = httpClient;
+    this.projectId = projectId;
+  }
+  messageCallbacks = [];
+  presenceCallbacks = [];
+  websocket = null;
+  isSubscribed = false;
+  reconnectTimer = null;
+  heartbeatTimer = null;
+  reconnectAttempts = 0;
+  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();
+      }
+    } catch (error) {
+      throw new BlinkRealtimeError(
+        `Failed to subscribe to channel ${this.channelName}: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  async unsubscribe() {
+    if (!this.isSubscribed) {
+      return;
+    }
+    if (this.websocket) {
+      const unsubscribeMessage = {
+        type: "unsubscribe",
+        payload: {
+          channel: this.channelName
+        }
+      };
+      this.websocket.send(JSON.stringify(unsubscribeMessage));
+    }
+    this.cleanup();
+  }
+  async publish(type, data, options = {}) {
+    try {
+      const response = await this.httpClient.realtimePublish(this.projectId, {
+        channel: this.channelName,
+        type,
+        data,
+        userId: options.userId,
+        metadata: options.metadata
+      });
+      return response.data.messageId;
+    } catch (error) {
+      throw new BlinkRealtimeError(
+        `Failed to publish message to channel ${this.channelName}: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  onMessage(callback) {
+    this.messageCallbacks.push(callback);
+    return () => {
+      const index = this.messageCallbacks.indexOf(callback);
+      if (index > -1) {
+        this.messageCallbacks.splice(index, 1);
+      }
+    };
+  }
+  onPresence(callback) {
+    this.presenceCallbacks.push(callback);
+    return () => {
+      const index = this.presenceCallbacks.indexOf(callback);
+      if (index > -1) {
+        this.presenceCallbacks.splice(index, 1);
+      }
+    };
+  }
+  async getPresence() {
+    try {
+      const response = await this.httpClient.realtimeGetPresence(this.projectId, this.channelName);
+      return response.data.users;
+    } catch (error) {
+      throw new BlinkRealtimeError(
+        `Failed to get presence for channel ${this.channelName}: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  async getMessages(options = {}) {
+    try {
+      const response = await this.httpClient.realtimeGetMessages(this.projectId, {
+        channel: this.channelName,
+        limit: options.limit,
+        start: options.after,
+        // after = start from this ID onwards
+        end: options.before
+        // before = end at this ID
+      });
+      return response.data.messages;
+    } catch (error) {
+      throw new BlinkRealtimeError(
+        `Failed to get messages for channel ${this.channelName}: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  async connectWebSocket() {
+    if (this.websocket && this.websocket.readyState === 1) {
+      return;
+    }
+    return new Promise((resolve, reject) => {
+      try {
+        const baseUrl = this.httpClient.projectId.includes("localhost") ? "ws://localhost:3000" : "wss://core.blink.new";
+        const wsUrl = `${baseUrl}?project_id=${this.projectId}`;
+        const WSClass = getWebSocketClass();
+        this.websocket = new WSClass(wsUrl);
+        if (!this.websocket) {
+          reject(new BlinkRealtimeError("Failed to create WebSocket instance"));
+          return;
+        }
+        this.websocket.onopen = () => {
+          console.log(`\u{1F517} Connected to realtime for project ${this.projectId}`);
+          this.reconnectAttempts = 0;
+          resolve();
+        };
+        this.websocket.onmessage = (event) => {
+          try {
+            const message = JSON.parse(event.data);
+            this.handleWebSocketMessage(message);
+          } catch (error) {
+            console.error("Failed to parse WebSocket message:", error);
+          }
+        };
+        this.websocket.onclose = () => {
+          console.log(`\u{1F50C} Disconnected from realtime for project ${this.projectId}`);
+          this.isSubscribed = false;
+          this.scheduleReconnect();
+        };
+        this.websocket.onerror = (error) => {
+          console.error("WebSocket error:", error);
+          reject(new BlinkRealtimeError("WebSocket connection failed"));
+        };
+        setTimeout(() => {
+          if (this.websocket?.readyState !== 1) {
+            reject(new BlinkRealtimeError("WebSocket connection timeout"));
+          }
+        }, 5e3);
+      } catch (error) {
+        reject(new BlinkRealtimeError(`Failed to create WebSocket connection: ${error instanceof Error ? error.message : "Unknown error"}`));
+      }
+    });
+  }
+  handleWebSocketMessage(message) {
+    switch (message.type) {
+      case "message":
+        this.messageCallbacks.forEach((callback) => {
+          try {
+            callback(message.payload);
+          } catch (error) {
+            console.error("Error in message callback:", error);
+          }
+        });
+        break;
+      case "presence":
+        this.presenceCallbacks.forEach((callback) => {
+          try {
+            callback(message.payload.data || []);
+          } catch (error) {
+            console.error("Error in presence callback:", error);
+          }
+        });
+        break;
+      case "subscribed":
+        console.log(`\u2705 Subscribed to channel: ${message.payload.channel}`);
+        break;
+      case "unsubscribed":
+        console.log(`\u274C Unsubscribed from channel: ${message.payload.channel}`);
+        break;
+      case "pong":
+        break;
+      case "error":
+        console.error("Realtime error:", message.payload.error);
+        break;
+      default:
+        console.log("Unknown message type:", message.type);
+    }
+  }
+  startHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+    }
+    this.heartbeatTimer = globalThis.setInterval(() => {
+      if (this.websocket && this.websocket.readyState === 1) {
+        this.websocket.send(JSON.stringify({ type: "ping", payload: {} }));
+      }
+    }, 25e3);
+  }
+  scheduleReconnect() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+    }
+    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) {
+        try {
+          await this.connectWebSocket();
+          if (this.websocket) {
+            const subscribeMessage = {
+              type: "subscribe",
+              payload: {
+                channel: this.channelName
+              }
+            };
+            this.websocket.send(JSON.stringify(subscribeMessage));
+            this.startHeartbeat();
+          }
+        } catch (error) {
+          console.error("Reconnection failed:", error);
+          this.scheduleReconnect();
+        }
+      }
+    }, delay);
+  }
+  cleanup() {
+    this.isSubscribed = false;
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.websocket) {
+      this.websocket.close();
+      this.websocket = null;
+    }
+    this.messageCallbacks = [];
+    this.presenceCallbacks = [];
+  }
+};
+var BlinkRealtimeImpl = class {
+  constructor(httpClient, projectId) {
+    this.httpClient = httpClient;
+    this.projectId = projectId;
+  }
+  channels = /* @__PURE__ */ new Map();
+  handlers = {};
+  channel(name) {
+    if (!this.channels.has(name)) {
+      this.channels.set(name, new BlinkRealtimeChannel(name, this.httpClient, this.projectId));
+    }
+    return this.channels.get(name);
+  }
+  async subscribe(channelName, callback, options = {}) {
+    const channel = this.channel(channelName);
+    await channel.subscribe(options);
+    const state = this.handlers[channelName] ??= {
+      msgHandlers: /* @__PURE__ */ new Set(),
+      presHandlers: /* @__PURE__ */ new Set(),
+      subscribed: true
+    };
+    state.msgHandlers.add(callback);
+    const messageUnsub = channel.onMessage(callback);
+    return () => {
+      messageUnsub();
+      state.msgHandlers.delete(callback);
+      if (state.msgHandlers.size === 0 && state.presHandlers.size === 0) {
+        channel.unsubscribe();
+        delete this.handlers[channelName];
+      }
+    };
+  }
+  async publish(channelName, type, data, options = {}) {
+    const channel = this.channel(channelName);
+    return channel.publish(type, data, options);
+  }
+  async presence(channelName) {
+    const channel = this.channel(channelName);
+    return channel.getPresence();
+  }
+  onPresence(channelName, callback) {
+    const channel = this.channel(channelName);
+    const state = this.handlers[channelName] ??= {
+      msgHandlers: /* @__PURE__ */ new Set(),
+      presHandlers: /* @__PURE__ */ new Set(),
+      subscribed: false
+    };
+    state.presHandlers.add(callback);
+    const presenceUnsub = channel.onPresence(callback);
+    return () => {
+      presenceUnsub();
+      state.presHandlers.delete(callback);
+      if (state.msgHandlers.size === 0 && state.presHandlers.size === 0) {
+        channel.unsubscribe();
+        delete this.handlers[channelName];
+      }
+    };
+  }
+};
+
 // src/client.ts
 var BlinkClientImpl = class {
   auth;
@@ -2454,6 +2810,7 @@ var BlinkClientImpl = class {
   storage;
   ai;
   data;
+  realtime;
   httpClient;
   constructor(config) {
     this.auth = new BlinkAuth(config);
@@ -2466,6 +2823,7 @@ var BlinkClientImpl = class {
     this.storage = new BlinkStorageImpl(this.httpClient);
     this.ai = new BlinkAIImpl(this.httpClient);
     this.data = new BlinkDataImpl(this.httpClient, config.projectId);
+    this.realtime = new BlinkRealtimeImpl(this.httpClient, config.projectId);
   }
 };
 function createClient(config) {
@@ -2479,6 +2837,6 @@ function createClient(config) {
   return new BlinkClientImpl(clientConfig);
 }
 
-export { BlinkAIImpl, BlinkDataImpl, BlinkDatabase, BlinkStorageImpl, BlinkTable, createClient };
+export { BlinkAIImpl, BlinkDataImpl, BlinkDatabase, BlinkRealtimeChannel, BlinkRealtimeImpl, BlinkStorageImpl, BlinkTable, createClient };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/package.json

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