@blinkdotnew/sdk 0.5.0 → 0.6.0

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, BlinkData, BlinkStorage, BlinkUser, CreateOptions, DataExtraction, FileObject, FilterCondition, ImageGenerationRequest, ImageGenerationResponse, ListResponse, Message, ObjectGenerationRequest, ObjectGenerationResponse, QueryOptions, 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
@@ -215,7 +215,7 @@ interface BlinkData {
     fetchAsync(request: Omit<FetchRequest, 'async'>): Promise<AsyncFetchResponse>;
     search(query: string, options?: {
         location?: string;
-        type?: 'news' | 'images' | 'videos' | 'shopping';
+        type?: 'news' | 'images' | 'image' | 'videos' | 'video' | 'shopping' | 'shop';
         language?: string;
         limit?: number;
     }): Promise<SearchResponse>;
@@ -242,7 +242,7 @@ declare class BlinkDataImpl implements BlinkData {
     fetchAsync(request: Omit<FetchRequest, 'async'>): Promise<AsyncFetchResponse>;
     search(query: string, options?: {
         location?: string;
-        type?: 'news' | 'images' | 'videos' | 'shopping';
+        type?: 'news' | 'images' | 'image' | 'videos' | 'video' | 'shopping' | 'shop';
         language?: string;
         limit?: number;
     }): Promise<SearchResponse>;
@@ -259,6 +259,7 @@ interface BlinkClient {
     storage: BlinkStorage;
     ai: BlinkAI;
     data: BlinkData;
+    realtime: BlinkRealtime;
 }
 /**
  * Create a new Blink client instance
@@ -665,4 +666,55 @@ declare class BlinkAIImpl implements BlinkAI {
     transcribeAudio(options: TranscriptionRequest): Promise<TranscriptionResponse>;
 }
 
-export { type AuthStateChangeCallback, BlinkAIImpl, type BlinkClient, 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;
+    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;
+    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, BlinkData, BlinkStorage, BlinkUser, CreateOptions, DataExtraction, FileObject, FilterCondition, ImageGenerationRequest, ImageGenerationResponse, ListResponse, Message, ObjectGenerationRequest, ObjectGenerationResponse, QueryOptions, 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
@@ -215,7 +215,7 @@ interface BlinkData {
     fetchAsync(request: Omit<FetchRequest, 'async'>): Promise<AsyncFetchResponse>;
     search(query: string, options?: {
         location?: string;
-        type?: 'news' | 'images' | 'videos' | 'shopping';
+        type?: 'news' | 'images' | 'image' | 'videos' | 'video' | 'shopping' | 'shop';
         language?: string;
         limit?: number;
     }): Promise<SearchResponse>;
@@ -242,7 +242,7 @@ declare class BlinkDataImpl implements BlinkData {
     fetchAsync(request: Omit<FetchRequest, 'async'>): Promise<AsyncFetchResponse>;
     search(query: string, options?: {
         location?: string;
-        type?: 'news' | 'images' | 'videos' | 'shopping';
+        type?: 'news' | 'images' | 'image' | 'videos' | 'video' | 'shopping' | 'shop';
         language?: string;
         limit?: number;
     }): Promise<SearchResponse>;
@@ -259,6 +259,7 @@ interface BlinkClient {
     storage: BlinkStorage;
     ai: BlinkAI;
     data: BlinkData;
+    realtime: BlinkRealtime;
 }
 /**
  * Create a new Blink client instance
@@ -665,4 +666,55 @@ declare class BlinkAIImpl implements BlinkAI {
     transcribeAudio(options: TranscriptionRequest): Promise<TranscriptionResponse>;
 }
 
-export { type AuthStateChangeCallback, BlinkAIImpl, type BlinkClient, 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;
+    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;
+    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 };