@inf-minds/relay-client 0.0.1

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+import type { StreamClient, StreamClientOptions } from './types.js';
+export declare function createStreamClient(options: StreamClientOptions): StreamClient;

package/dist/client.js

@@ -0,0 +1,77 @@
+// ABOUTME: Stream client implementation
+// ABOUTME: Provides unified interface over transports with auto-fallback
+import { OFFSET_BEGINNING } from '@inf-minds/streams-protocol';
+import { createHTTPTransport } from './transports/http.js';
+import { createWebSocketTransport } from './transports/websocket.js';
+export function createStreamClient(options) {
+    const { baseUrl, auth, transport = 'auto' } = options;
+    const getToken = auth?.getToken ?? (auth?.token ? async () => auth.token : undefined);
+    // Select transport based on option
+    function selectTransport(preferred) {
+        switch (preferred) {
+            case 'websocket':
+                return createWebSocketTransport({ baseUrl, getToken });
+            case 'sse':
+                // SSE uses HTTP transport with ?live=sse
+                return createHTTPTransport({ baseUrl, getToken });
+            case 'http':
+            case 'auto':
+            default:
+                return createHTTPTransport({ baseUrl, getToken });
+        }
+    }
+    const activeTransport = selectTransport(transport);
+    // Connect WebSocket if using that transport
+    if (transport === 'websocket') {
+        activeTransport.connect?.();
+    }
+    return {
+        subscribe(streamId, opts = {}) {
+            const { offset: initialOffset, onEvent, persistOffset, loadOffset, } = opts;
+            let currentOffset = initialOffset ?? OFFSET_BEGINNING;
+            let status = {
+                upToDate: false,
+                closed: false,
+                offset: currentOffset,
+            };
+            // Load persisted offset if available
+            if (loadOffset) {
+                const loaded = loadOffset();
+                if (loaded instanceof Promise) {
+                    loaded.then((o) => {
+                        if (o)
+                            currentOffset = o;
+                    });
+                }
+                else if (loaded) {
+                    currentOffset = loaded;
+                }
+            }
+            const unsubscribe = activeTransport.subscribe(streamId, currentOffset, (event, newOffset) => {
+                currentOffset = newOffset;
+                status.offset = newOffset;
+                if (onEvent) {
+                    onEvent(event, newOffset);
+                }
+                if (persistOffset) {
+                    const result = persistOffset(newOffset);
+                    if (result instanceof Promise) {
+                        result.catch((err) => console.error('Failed to persist offset:', err));
+                    }
+                }
+            });
+            return {
+                get status() {
+                    return status;
+                },
+                get offset() {
+                    return currentOffset;
+                },
+                unsubscribe,
+            };
+        },
+        close() {
+            activeTransport.close();
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { StreamClient, StreamClientOptions, StreamSubscription, SubscribeOptions, StreamStatus, TransportType, ConnectionStatus, } from './types.js';
+export { createStreamClient } from './client.js';
+export { createHTTPTransport } from './transports/http.js';
+export { createWebSocketTransport } from './transports/websocket.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+// ABOUTME: Relay client entry point
+// ABOUTME: Exports createStreamClient and types
+export { createStreamClient } from './client.js';
+// Export transports for advanced use
+export { createHTTPTransport } from './transports/http.js';
+export { createWebSocketTransport } from './transports/websocket.js';

package/dist/transports/http.d.ts

@@ -0,0 +1,14 @@
+export interface HTTPTransportOptions {
+    baseUrl: string;
+    getToken?: () => Promise<string>;
+}
+export interface EventHandler {
+    (event: unknown, offset: string): void;
+}
+export interface Unsubscribe {
+    (): void;
+}
+export declare function createHTTPTransport(options: HTTPTransportOptions): {
+    subscribe(streamId: string, offset: string, handler: EventHandler): Unsubscribe;
+    close(): void;
+};

package/dist/transports/http.js

@@ -0,0 +1,63 @@
+// ABOUTME: HTTP long-poll transport implementation
+// ABOUTME: Polls /v1/streams endpoint with long-poll mode
+import { parseStreamHeaders, } from '@inf-minds/streams-protocol';
+export function createHTTPTransport(options) {
+    const subscriptions = new Map();
+    async function poll(streamId) {
+        const sub = subscriptions.get(streamId);
+        if (!sub || !sub.active)
+            return;
+        try {
+            const headers = {};
+            if (options.getToken) {
+                headers['Authorization'] = `Bearer ${await options.getToken()}`;
+            }
+            const url = `${options.baseUrl}/v1/streams/${streamId}?offset=${sub.offset}&live=long-poll`;
+            const response = await fetch(url, { headers });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            const streamHeaders = parseStreamHeaders(response.headers);
+            const events = await response.json();
+            for (const event of events) {
+                sub.handler(event, streamHeaders.nextOffset);
+            }
+            sub.offset = streamHeaders.nextOffset;
+            // Check if stream is closed
+            if (streamHeaders.closed) {
+                sub.active = false;
+                return;
+            }
+            // Continue polling
+            if (sub.active) {
+                setTimeout(() => poll(streamId), 100);
+            }
+        }
+        catch (error) {
+            console.error('HTTP transport error:', error);
+            // Retry after delay
+            if (sub.active) {
+                setTimeout(() => poll(streamId), 3000);
+            }
+        }
+    }
+    return {
+        subscribe(streamId, offset, handler) {
+            subscriptions.set(streamId, { offset, handler, active: true });
+            poll(streamId);
+            return () => {
+                const sub = subscriptions.get(streamId);
+                if (sub) {
+                    sub.active = false;
+                }
+                subscriptions.delete(streamId);
+            };
+        },
+        close() {
+            for (const sub of subscriptions.values()) {
+                sub.active = false;
+            }
+            subscriptions.clear();
+        },
+    };
+}

package/dist/transports/websocket.d.ts

@@ -0,0 +1,16 @@
+export interface WebSocketTransportOptions {
+    baseUrl: string;
+    getToken?: () => Promise<string>;
+}
+export interface EventHandler {
+    (event: unknown, offset: string): void;
+}
+export interface Unsubscribe {
+    (): void;
+}
+export declare function createWebSocketTransport(options: WebSocketTransportOptions): {
+    connect(): Promise<void>;
+    subscribe(streamId: string, offset: string, handler: EventHandler): Unsubscribe;
+    close(): void;
+    readonly ws: WebSocket | null;
+};

package/dist/transports/websocket.js

@@ -0,0 +1,91 @@
+// ABOUTME: WebSocket transport implementation
+// ABOUTME: Manages subscriptions and real-time event delivery
+import { serializeWSMessage, parseWSServerMessage, } from '@inf-minds/streams-protocol';
+export function createWebSocketTransport(options) {
+    let ws = null;
+    const subscriptions = new Map();
+    const pendingSubscribes = [];
+    function getWsUrl() {
+        const url = new URL(options.baseUrl);
+        url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+        url.pathname = '/ws';
+        return url.toString();
+    }
+    function send(msg) {
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(serializeWSMessage(msg));
+        }
+    }
+    function handleMessage(data) {
+        const msg = parseWSServerMessage(data);
+        if (!msg)
+            return;
+        switch (msg.type) {
+            case 'subscribed':
+                // Subscription confirmed
+                break;
+            case 'event':
+                const handler = subscriptions.get(msg.streamId);
+                if (handler) {
+                    handler(msg.event, msg.nextOffset);
+                }
+                break;
+            case 'status':
+                // Could trigger status callback
+                break;
+            case 'error':
+                console.error('WebSocket error:', msg.message);
+                break;
+            case 'pong':
+                // Keepalive response
+                break;
+        }
+    }
+    return {
+        async connect() {
+            return new Promise((resolve, reject) => {
+                ws = new WebSocket(getWsUrl());
+                ws.onopen = () => {
+                    // Send pending subscribes
+                    for (const { streamId, offset } of pendingSubscribes) {
+                        send({ type: 'subscribe', streamId, offset });
+                    }
+                    pendingSubscribes.length = 0;
+                    resolve();
+                };
+                ws.onmessage = (event) => {
+                    handleMessage(event.data);
+                };
+                ws.onerror = (error) => {
+                    reject(error);
+                };
+                ws.onclose = () => {
+                    ws = null;
+                };
+            });
+        },
+        subscribe(streamId, offset, handler) {
+            subscriptions.set(streamId, handler);
+            if (ws && ws.readyState === WebSocket.OPEN) {
+                send({ type: 'subscribe', streamId, offset });
+            }
+            else {
+                pendingSubscribes.push({ streamId, offset });
+            }
+            return () => {
+                subscriptions.delete(streamId);
+                send({ type: 'unsubscribe', streamId });
+            };
+        },
+        close() {
+            if (ws) {
+                ws.close();
+                ws = null;
+            }
+            subscriptions.clear();
+        },
+        get ws() {
+            return ws;
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,34 @@
+export type TransportType = 'websocket' | 'sse' | 'http' | 'auto';
+export type ConnectionStatus = 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'error';
+export interface StreamClientOptions {
+    baseUrl: string;
+    auth?: {
+        token?: string;
+        getToken?: () => Promise<string>;
+    };
+    transport?: TransportType;
+    onConnectionChange?: (status: ConnectionStatus) => void;
+}
+export interface SubscribeOptions<T> {
+    offset?: string;
+    onEvent?: (event: T, offset: string) => void;
+    onStatus?: (status: StreamStatus) => void;
+    onError?: (error: Error) => void;
+    onReconnect?: (offset: string) => void;
+    persistOffset?: (offset: string) => void | Promise<void>;
+    loadOffset?: () => string | undefined | Promise<string | undefined>;
+}
+export interface StreamStatus {
+    upToDate: boolean;
+    closed: boolean;
+    offset: string;
+}
+export interface StreamSubscription<T> {
+    readonly status: StreamStatus;
+    readonly offset: string;
+    unsubscribe(): void;
+}
+export interface StreamClient {
+    subscribe<T>(streamId: string, options?: SubscribeOptions<T>): StreamSubscription<T>;
+    close(): void;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// ABOUTME: Type definitions for relay client
+// ABOUTME: Defines client options, subscription, and callbacks
+export {};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@inf-minds/relay-client",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@inf-minds/streams-protocol": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}