@flightdev/realtime 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Flight Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,410 @@
+# @flight-framework/realtime
+
+Real-time communication for Flight Framework. Unified API for WebSocket and Server-Sent Events (SSE).
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Adapters](#adapters)
+- [Channels](#channels)
+- [Presence](#presence)
+- [React Integration](#react-integration)
+- [Vue Integration](#vue-integration)
+- [Server-Side Events](#server-side-events)
+- [API Reference](#api-reference)
+- [License](#license)
+
+---
+
+## Features
+
+- Multiple transport adapters (WebSocket, SSE)
+- Pub/sub channels with room support
+- Presence tracking (who's online)
+- Automatic reconnection with backoff
+- Message history and replay
+- Binary data support
+- React and Vue hooks
+- Edge-compatible SSE adapter
+
+---
+
+## Installation
+
+```bash
+npm install @flight-framework/realtime
+```
+
+---
+
+## Quick Start
+
+### Client
+
+```typescript
+import { createRealtime } from '@flight-framework/realtime';
+import { websocket } from '@flight-framework/realtime/websocket';
+
+const realtime = createRealtime(websocket({
+    url: 'wss://api.example.com/ws',
+}));
+
+// Connect
+await realtime.connect();
+
+// Subscribe to a channel
+const chat = realtime.channel('chat:general');
+
+chat.on('message', (data) => {
+    console.log('Received:', data);
+});
+
+// Send a message
+chat.send('message', { text: 'Hello everyone!' });
+```
+
+### Server
+
+```typescript
+import { createServer } from '@flight-framework/realtime/server';
+
+const server = createServer({ port: 3001 });
+
+server.on('connection', (socket) => {
+    console.log('Client connected:', socket.id);
+    
+    socket.on('message', (data) => {
+        // Broadcast to all clients in the channel
+        server.to('chat:general').emit('message', data);
+    });
+});
+```
+
+---
+
+## Adapters
+
+### WebSocket (Full Duplex)
+
+Bidirectional communication for real-time apps.
+
+```typescript
+import { websocket } from '@flight-framework/realtime/websocket';
+
+const adapter = websocket({
+    url: 'wss://api.example.com/ws',
+    protocols: ['v1'],
+    reconnect: true,
+    reconnectDelay: 1000,
+    maxReconnectDelay: 30000,
+    pingInterval: 25000,
+});
+```
+
+### SSE (Server-Sent Events)
+
+One-way server-to-client, edge-compatible.
+
+```typescript
+import { sse } from '@flight-framework/realtime/sse';
+
+const adapter = sse({
+    url: '/api/events',
+    withCredentials: true,
+    retryDelay: 3000,
+});
+```
+
+---
+
+## Channels
+
+### Subscribe to Channel
+
+```typescript
+const channel = realtime.channel('notifications:user_123');
+
+channel.on('new', (notification) => {
+    showNotification(notification);
+});
+
+channel.on('read', (id) => {
+    markAsRead(id);
+});
+```
+
+### Send to Channel
+
+```typescript
+channel.send('typing', { userId: 'user_123' });
+```
+
+### Leave Channel
+
+```typescript
+channel.leave();
+```
+
+### Channel Events
+
+```typescript
+channel.on('join', () => console.log('Joined channel'));
+channel.on('leave', () => console.log('Left channel'));
+channel.on('error', (err) => console.error('Channel error:', err));
+```
+
+---
+
+## Presence
+
+Track who's online in a channel:
+
+```typescript
+const channel = realtime.channel('room:lobby');
+
+// Track current user
+channel.presence.enter({
+    userId: 'user_123',
+    name: 'John',
+    status: 'online',
+});
+
+// Get current members
+const members = channel.presence.get();
+console.log('Online:', members);
+
+// Listen for changes
+channel.presence.on('join', (member) => {
+    console.log(`${member.name} joined`);
+});
+
+channel.presence.on('leave', (member) => {
+    console.log(`${member.name} left`);
+});
+
+channel.presence.on('update', (member) => {
+    console.log(`${member.name} updated status`);
+});
+
+// Update presence
+channel.presence.update({ status: 'away' });
+
+// Leave
+channel.presence.leave();
+```
+
+---
+
+## React Integration
+
+### RealtimeProvider
+
+```tsx
+import { RealtimeProvider } from '@flight-framework/realtime/react';
+
+function App() {
+    return (
+        <RealtimeProvider client={realtime}>
+            <ChatRoom />
+        </RealtimeProvider>
+    );
+}
+```
+
+### useRealtime Hook
+
+```tsx
+import { useRealtime } from '@flight-framework/realtime/react';
+
+function ConnectionStatus() {
+    const { state, connect, disconnect } = useRealtime();
+    
+    return (
+        <div>
+            Status: {state}
+            {state === 'disconnected' && (
+                <button onClick={connect}>Reconnect</button>
+            )}
+        </div>
+    );
+}
+```
+
+### useChannel Hook
+
+```tsx
+import { useChannel } from '@flight-framework/realtime/react';
+
+function ChatRoom({ roomId }) {
+    const [messages, setMessages] = useState([]);
+    
+    const { send } = useChannel(`chat:${roomId}`, {
+        onMessage: (data) => {
+            setMessages(prev => [...prev, data]);
+        },
+    });
+    
+    const handleSend = (text) => {
+        send('message', { text, timestamp: Date.now() });
+    };
+    
+    return (
+        <div>
+            {messages.map(msg => (
+                <div key={msg.timestamp}>{msg.text}</div>
+            ))}
+            <MessageInput onSend={handleSend} />
+        </div>
+    );
+}
+```
+
+### usePresence Hook
+
+```tsx
+import { usePresence } from '@flight-framework/realtime/react';
+
+function OnlineUsers({ roomId }) {
+    const { members, enter, leave } = usePresence(`room:${roomId}`);
+    
+    useEffect(() => {
+        enter({ name: currentUser.name });
+        return () => leave();
+    }, []);
+    
+    return (
+        <ul>
+            {members.map(member => (
+                <li key={member.id}>{member.name}</li>
+            ))}
+        </ul>
+    );
+}
+```
+
+---
+
+## Vue Integration
+
+### Composables
+
+```vue
+<script setup>
+import { useRealtime, useChannel, usePresence } from '@flight-framework/realtime/vue';
+
+const { state } = useRealtime();
+const { messages, send } = useChannel('chat:general');
+const { members, enter } = usePresence('room:lobby');
+
+onMounted(() => {
+    enter({ name: user.name });
+});
+
+const sendMessage = (text) => {
+    send('message', { text });
+};
+</script>
+
+<template>
+    <div>
+        <span>Status: {{ state }}</span>
+        <div v-for="msg in messages" :key="msg.id">
+            {{ msg.text }}
+        </div>
+        <input @keyup.enter="sendMessage($event.target.value)" />
+    </div>
+</template>
+```
+
+---
+
+## Server-Side Events
+
+### SSE Handler
+
+```typescript
+// src/routes/api/events.get.ts
+import { createSSEResponse } from '@flight-framework/realtime/sse';
+
+export async function GET(request: Request) {
+    const userId = getUserId(request);
+    
+    return createSSEResponse(request, (send, close) => {
+        // Subscribe to events
+        const unsubscribe = eventBus.subscribe(userId, (event) => {
+            send(event.type, event.data);
+        });
+        
+        // Cleanup on disconnect
+        return () => {
+            unsubscribe();
+        };
+    });
+}
+```
+
+### SSE Client
+
+```typescript
+const events = new EventSource('/api/events');
+
+events.addEventListener('notification', (e) => {
+    const data = JSON.parse(e.data);
+    showNotification(data);
+});
+
+events.addEventListener('message', (e) => {
+    const data = JSON.parse(e.data);
+    addMessage(data);
+});
+```
+
+---
+
+## API Reference
+
+### createRealtime Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `reconnect` | `boolean` | `true` | Auto-reconnect |
+| `reconnectDelay` | `number` | `1000` | Initial delay (ms) |
+| `maxReconnectDelay` | `number` | `30000` | Max delay (ms) |
+| `timeout` | `number` | `20000` | Connection timeout |
+
+### Realtime Methods
+
+| Method | Description |
+|--------|-------------|
+| `connect()` | Connect to server |
+| `disconnect()` | Disconnect |
+| `channel(name)` | Get or create channel |
+| `on(event, handler)` | Listen to events |
+| `off(event, handler)` | Remove listener |
+
+### Channel Methods
+
+| Method | Description |
+|--------|-------------|
+| `send(event, data)` | Send message |
+| `on(event, handler)` | Listen to event |
+| `off(event, handler)` | Remove listener |
+| `leave()` | Leave channel |
+| `presence` | Presence API |
+
+### Connection States
+
+| State | Description |
+|-------|-------------|
+| `connecting` | Establishing connection |
+| `connected` | Connected and ready |
+| `disconnected` | Not connected |
+| `reconnecting` | Attempting reconnect |
+
+---
+
+## License
+
+MIT

package/dist/adapters/sse.d.ts

@@ -0,0 +1,59 @@
+import { RealtimeAdapterFactory } from '../index.js';
+
+/**
+ * SSE (Server-Sent Events) Adapter for @flightdev/realtime
+ *
+ * Edge-compatible transport using SSE for server-to-client
+ * and fetch POST for client-to-server communication.
+ *
+ * @example
+ * ```typescript
+ * import { createRealtime } from '@flightdev/realtime';
+ * import { sse } from '@flightdev/realtime/sse';
+ *
+ * const realtime = createRealtime(sse({
+ *   url: '/api/realtime',
+ * }));
+ * ```
+ */
+
+interface SSEConfig {
+    /** URL for SSE endpoint */
+    url: string;
+    /** URL for sending messages (defaults to same as url) */
+    sendUrl?: string;
+    /** Retry delay on disconnect */
+    retryDelay?: number;
+    /** Custom headers */
+    headers?: Record<string, string>;
+}
+/**
+ * Create an SSE adapter
+ *
+ * SSE provides server-to-client streaming, with fetch POST for
+ * client-to-server messages. Works on Edge runtimes.
+ */
+declare const sse: RealtimeAdapterFactory<SSEConfig>;
+
+/**
+ * Create an SSE response for server-side streaming
+ *
+ * @example
+ * ```typescript
+ * // In your API route
+ * export async function GET(request: Request) {
+ *   return createSSEResponse(request, (send) => {
+ *     // Subscribe to updates
+ *     const unsubscribe = mySource.subscribe((data) => {
+ *       send('message', data);
+ *     });
+ *
+ *     // Cleanup on close
+ *     return () => unsubscribe();
+ *   });
+ * }
+ * ```
+ */
+declare function createSSEResponse(_request: Request, handler: (send: (event: string, data: unknown) => void) => (() => void) | void): Response;
+
+export { type SSEConfig, createSSEResponse, sse as default, sse };

package/dist/adapters/sse.js

@@ -0,0 +1,188 @@
+import { createMessage, parseMessage } from '../chunk-D6OMTDYP.js';
+
+// src/adapters/sse.ts
+var SSEChannel = class {
+  name;
+  subscribers = /* @__PURE__ */ new Map();
+  allSubscribers = /* @__PURE__ */ new Set();
+  sendFn;
+  constructor(name, sendFn) {
+    this.name = name;
+    this.sendFn = sendFn;
+  }
+  subscribe(callback) {
+    this.allSubscribers.add(callback);
+    return () => this.allSubscribers.delete(callback);
+  }
+  on(event, callback) {
+    if (!this.subscribers.has(event)) {
+      this.subscribers.set(event, /* @__PURE__ */ new Set());
+    }
+    this.subscribers.get(event).add(callback);
+    return () => this.subscribers.get(event)?.delete(callback);
+  }
+  broadcast(data, event = "message") {
+    this.sendFn(this.name, event, data);
+  }
+  send(data, event = "message") {
+    this.broadcast(data, event);
+  }
+  leave() {
+    this.allSubscribers.clear();
+    this.subscribers.clear();
+  }
+  _handleMessage(message) {
+    this.allSubscribers.forEach((cb) => cb(message));
+    const eventSubs = this.subscribers.get(message.event);
+    eventSubs?.forEach((cb) => cb(message));
+  }
+};
+var sse = (config) => {
+  if (!config?.url) {
+    throw new Error("@flightdev/realtime: SSE requires a url configuration");
+  }
+  const {
+    url,
+    sendUrl = url,
+    retryDelay = 3e3,
+    headers = {}
+  } = config;
+  let eventSource = null;
+  let state = "disconnected";
+  const channels = /* @__PURE__ */ new Map();
+  const stateCallbacks = /* @__PURE__ */ new Set();
+  const errorCallbacks = /* @__PURE__ */ new Set();
+  const subscribedChannels = /* @__PURE__ */ new Set();
+  function setState(newState) {
+    state = newState;
+    stateCallbacks.forEach((cb) => cb(state));
+  }
+  async function send(channel, event, data) {
+    const message = createMessage(channel, event, data);
+    try {
+      const response = await fetch(sendUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...headers
+        },
+        body: JSON.stringify(message)
+      });
+      if (!response.ok) {
+        throw new Error(`Failed to send message: ${response.status}`);
+      }
+    } catch (error) {
+      errorCallbacks.forEach((cb) => cb(error));
+    }
+  }
+  function handleMessage(event) {
+    const message = parseMessage(event.data);
+    if (!message) return;
+    const channel = channels.get(message.channel);
+    if (channel) {
+      channel._handleMessage(message);
+    }
+  }
+  const adapter = {
+    name: "sse",
+    get state() {
+      return state;
+    },
+    async connect() {
+      if (state === "connected" || state === "connecting") {
+        return;
+      }
+      setState("connecting");
+      return new Promise((resolve, reject) => {
+        const sseUrl = new URL(url, globalThis.location?.origin ?? "http://localhost");
+        subscribedChannels.forEach((ch) => {
+          sseUrl.searchParams.append("channel", ch);
+        });
+        eventSource = new EventSource(sseUrl.toString());
+        eventSource.onopen = () => {
+          setState("connected");
+          resolve();
+        };
+        eventSource.onerror = (_event) => {
+          if (state === "connecting") {
+            setState("disconnected");
+            reject(new Error("SSE connection failed"));
+          } else {
+            setState("reconnecting");
+            setTimeout(() => {
+              adapter.connect().catch(() => {
+              });
+            }, retryDelay);
+          }
+          errorCallbacks.forEach((cb) => cb(new Error("SSE error")));
+        };
+        eventSource.onmessage = handleMessage;
+        eventSource.addEventListener("realtime", (e) => {
+          handleMessage(e);
+        });
+      });
+    },
+    disconnect() {
+      eventSource?.close();
+      eventSource = null;
+      setState("disconnected");
+    },
+    channel(name, _options) {
+      if (!channels.has(name)) {
+        channels.set(name, new SSEChannel(name, send));
+        subscribedChannels.add(name);
+        if (state === "connected") {
+          adapter.disconnect();
+          adapter.connect().catch(() => {
+          });
+        }
+      }
+      return channels.get(name);
+    },
+    onStateChange(callback) {
+      stateCallbacks.add(callback);
+      return () => stateCallbacks.delete(callback);
+    },
+    onError(callback) {
+      errorCallbacks.add(callback);
+      return () => errorCallbacks.delete(callback);
+    },
+    send(channel, event, data) {
+      send(channel, event, data).catch(() => {
+      });
+    }
+  };
+  return adapter;
+};
+var sse_default = sse;
+function createSSEResponse(_request, handler) {
+  const encoder = new TextEncoder();
+  let cleanup;
+  const stream = new ReadableStream({
+    start(controller) {
+      function send(event, data) {
+        const message = `event: ${event}
+data: ${JSON.stringify(data)}
+
+`;
+        controller.enqueue(encoder.encode(message));
+      }
+      cleanup = handler(send);
+      send("connected", { timestamp: Date.now() });
+    },
+    cancel() {
+      cleanup?.();
+    }
+  });
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      "Connection": "keep-alive"
+    }
+  });
+}
+
+export { createSSEResponse, sse_default as default, sse };
+//# sourceMappingURL=sse.js.map
+//# sourceMappingURL=sse.js.map