@agentuity/frontend 0.0.100

package/dist/websocket-manager.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Message handler callback type
+ */
+export type MessageHandler<T = unknown> = (data: T) => void;
+/**
+ * WebSocket state change callback types
+ */
+export interface WebSocketCallbacks<TOutput = unknown> {
+    /** Called when connection is established */
+    onConnect?: () => void;
+    /** Called when connection is closed */
+    onDisconnect?: () => void;
+    /** Called when an error occurs */
+    onError?: (error: Error) => void;
+    /** Called when a message is received */
+    onMessage?: MessageHandler<TOutput>;
+}
+/**
+ * Options for WebSocketManager
+ */
+export interface WebSocketManagerOptions<TOutput = unknown> {
+    /** WebSocket URL */
+    url: string;
+    /** Callbacks for state changes */
+    callbacks?: WebSocketCallbacks<TOutput>;
+    /** Reconnection configuration */
+    reconnect?: {
+        threshold?: number;
+        baseDelay?: number;
+        factor?: number;
+        maxDelay?: number;
+        jitter?: number;
+    };
+}
+/**
+ * WebSocket manager state
+ */
+export interface WebSocketManagerState {
+    /** Whether WebSocket is currently connected */
+    isConnected: boolean;
+    /** Current error, if any */
+    error: Error | null;
+    /** WebSocket ready state */
+    readyState: number;
+}
+/**
+ * Generic WebSocket connection manager with automatic reconnection,
+ * message queuing, and handler management.
+ *
+ * Framework-agnostic - can be used with React, Svelte, Vue, or vanilla JS.
+ */
+export declare class WebSocketManager<TInput = unknown, TOutput = unknown> {
+    private ws;
+    private manualClose;
+    private pendingMessages;
+    private queuedMessages;
+    private messageHandler;
+    private reconnectManager;
+    private callbacks;
+    private url;
+    private reconnectConfig;
+    constructor(options: WebSocketManagerOptions<TOutput>);
+    /**
+     * Connect to the WebSocket server
+     */
+    connect(): void;
+    /**
+     * Send data through the WebSocket.
+     * Messages are queued if not currently connected.
+     */
+    send(data: TInput): void;
+    /**
+     * Set the message handler.
+     * Any buffered messages will be delivered immediately.
+     */
+    setMessageHandler(handler: MessageHandler<TOutput>): void;
+    /**
+     * Get current state
+     */
+    getState(): WebSocketManagerState;
+    /**
+     * Close the WebSocket connection and cleanup
+     */
+    close(): void;
+    /**
+     * Dispose of the manager (alias for close)
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=websocket-manager.d.ts.map

package/dist/websocket-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-manager.d.ts","sourceRoot":"","sources":["../src/websocket-manager.ts"],"names":[],"mappings":"AAqBA;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,OAAO,GAAG,OAAO;IACpD,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,kCAAkC;IAClC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,wCAAwC;IACxC,SAAS,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB,CAAC,OAAO,GAAG,OAAO;IACzD,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,SAAS,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACxC,iCAAiC;IACjC,SAAS,CAAC,EAAE;QACX,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,+CAA+C;IAC/C,WAAW,EAAE,OAAO,CAAC;IACrB,4BAA4B;IAC5B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAChE,OAAO,CAAC,EAAE,CAAwB;IAClC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,eAAe,CAAiB;IACxC,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,cAAc,CAAsC;IAC5D,OAAO,CAAC,gBAAgB,CAA+B;IACvD,OAAO,CAAC,SAAS,CAA8B;IAC/C,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,eAAe,CAAuE;gBAElF,OAAO,EAAE,uBAAuB,CAAC,OAAO,CAAC;IAYrD;;OAEG;IACH,OAAO,IAAI,IAAI;IAmEf;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAQxB;;;OAGG;IACH,iBAAiB,CAAC,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,GAAG,IAAI;IAOzD;;OAEG;IACH,QAAQ,IAAI,qBAAqB;IAQjC;;OAEG;IACH,KAAK,IAAI,IAAI;IAqBb;;OAEG;IACH,OAAO,IAAI,IAAI;CAGf"}

package/dist/websocket-manager.js

@@ -0,0 +1,163 @@
+import { createReconnectManager } from './reconnect';
+import { deserializeData } from './serialization';
+/**
+ * Serialize data for WebSocket transmission
+ */
+const serializeWSData = (data) => {
+    if (typeof data === 'string') {
+        return data;
+    }
+    if (typeof data === 'object') {
+        if (data instanceof ArrayBuffer || ArrayBuffer.isView(data) || data instanceof Blob) {
+            return data;
+        }
+        return JSON.stringify(data);
+    }
+    throw new Error('unsupported data type for websocket: ' + typeof data);
+};
+/**
+ * Generic WebSocket connection manager with automatic reconnection,
+ * message queuing, and handler management.
+ *
+ * Framework-agnostic - can be used with React, Svelte, Vue, or vanilla JS.
+ */
+export class WebSocketManager {
+    ws;
+    manualClose = false;
+    pendingMessages = [];
+    queuedMessages = [];
+    messageHandler;
+    reconnectManager;
+    callbacks;
+    url;
+    reconnectConfig;
+    constructor(options) {
+        this.url = options.url;
+        this.callbacks = options.callbacks || {};
+        this.reconnectConfig = {
+            threshold: options.reconnect?.threshold ?? 0,
+            baseDelay: options.reconnect?.baseDelay ?? 500,
+            factor: options.reconnect?.factor ?? 2,
+            maxDelay: options.reconnect?.maxDelay ?? 30000,
+            jitter: options.reconnect?.jitter ?? 500,
+        };
+    }
+    /**
+     * Connect to the WebSocket server
+     */
+    connect() {
+        if (this.manualClose)
+            return;
+        this.ws = new WebSocket(this.url);
+        this.ws.onopen = () => {
+            this.reconnectManager?.recordSuccess();
+            this.callbacks.onConnect?.();
+            // Flush queued messages
+            if (this.queuedMessages.length > 0) {
+                this.queuedMessages.forEach((msg) => this.ws.send(serializeWSData(msg)));
+                this.queuedMessages = [];
+            }
+        };
+        this.ws.onerror = () => {
+            const error = new Error('WebSocket error');
+            this.callbacks.onError?.(error);
+        };
+        this.ws.onclose = (evt) => {
+            this.ws = undefined;
+            this.callbacks.onDisconnect?.();
+            if (this.manualClose) {
+                this.queuedMessages = [];
+                return;
+            }
+            if (evt.code !== 1000) {
+                const error = new Error(`WebSocket closed: ${evt.code} ${evt.reason || ''}`);
+                this.callbacks.onError?.(error);
+            }
+            this.reconnectManager?.recordFailure();
+        };
+        this.ws.onmessage = (event) => {
+            const payload = deserializeData(event.data);
+            // Call the registered message handler
+            if (this.messageHandler) {
+                this.messageHandler(payload);
+            }
+            else {
+                // Buffer messages until a handler is set
+                this.pendingMessages.push(payload);
+            }
+            // Also call the callback if provided
+            this.callbacks.onMessage?.(payload);
+        };
+        // Setup reconnect manager
+        if (!this.reconnectManager) {
+            this.reconnectManager = createReconnectManager({
+                onReconnect: () => this.connect(),
+                threshold: this.reconnectConfig.threshold,
+                baseDelay: this.reconnectConfig.baseDelay,
+                factor: this.reconnectConfig.factor,
+                maxDelay: this.reconnectConfig.maxDelay,
+                jitter: this.reconnectConfig.jitter,
+                enabled: () => !this.manualClose,
+            });
+        }
+    }
+    /**
+     * Send data through the WebSocket.
+     * Messages are queued if not currently connected.
+     */
+    send(data) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(serializeWSData(data));
+        }
+        else {
+            this.queuedMessages.push(data);
+        }
+    }
+    /**
+     * Set the message handler.
+     * Any buffered messages will be delivered immediately.
+     */
+    setMessageHandler(handler) {
+        this.messageHandler = handler;
+        // Flush pending messages
+        this.pendingMessages.forEach(handler);
+        this.pendingMessages = [];
+    }
+    /**
+     * Get current state
+     */
+    getState() {
+        return {
+            isConnected: this.ws?.readyState === WebSocket.OPEN,
+            error: null, // Error state managed externally via callbacks
+            readyState: this.ws?.readyState ?? WebSocket.CLOSED,
+        };
+    }
+    /**
+     * Close the WebSocket connection and cleanup
+     */
+    close() {
+        this.manualClose = true;
+        this.reconnectManager?.dispose();
+        if (this.ws) {
+            this.ws.onopen = null;
+            this.ws.onerror = null;
+            this.ws.onclose = null;
+            this.ws.onmessage = null;
+            this.ws.close();
+        }
+        this.ws = undefined;
+        this.messageHandler = undefined;
+        this.pendingMessages = [];
+        this.queuedMessages = [];
+        // Notify disconnect callback
+        this.callbacks.onDisconnect?.();
+    }
+    /**
+     * Dispose of the manager (alias for close)
+     */
+    dispose() {
+        this.close();
+    }
+}
+//# sourceMappingURL=websocket-manager.js.map

package/dist/websocket-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-manager.js","sourceRoot":"","sources":["../src/websocket-manager.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+	"name": "@agentuity/frontend",
+	"version": "0.0.100",
+	"license": "Apache-2.0",
+	"author": "Agentuity employees and contributors",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"files": [
+		"AGENTS.md",
+		"README.md",
+		"dist",
+		"src"
+	],
+	"scripts": {
+		"clean": "rm -rf dist",
+		"build": "bunx tsc --build --force",
+		"typecheck": "bunx tsc --noEmit",
+		"test": "bun test",
+		"prepublishOnly": "bun run clean && bun run build"
+	},
+	"dependencies": {},
+	"devDependencies": {
+		"@agentuity/test-utils": "workspace:*",
+		"@types/bun": "latest",
+		"bun-types": "latest",
+		"typescript": "^5.9.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"sideEffects": false
+}

package/src/env.ts

@@ -0,0 +1,9 @@
+export const getProcessEnv = (key: string): string | undefined => {
+	if (typeof process !== 'undefined' && process.env) {
+		return process.env[key];
+	}
+	if (typeof import.meta.env !== 'undefined') {
+		return import.meta.env[key];
+	}
+	return undefined;
+};

package/src/eventstream-manager.ts

@@ -0,0 +1,203 @@
+import { createReconnectManager, type ReconnectManager } from './reconnect';
+import { deserializeData } from './serialization';
+
+/**
+ * Message handler callback type
+ */
+export type MessageHandler<T = unknown> = (data: T) => void;
+
+/**
+ * EventStream state change callback types
+ */
+export interface EventStreamCallbacks<TOutput = unknown> {
+	/** Called when connection is established */
+	onConnect?: () => void;
+	/** Called when connection is closed */
+	onDisconnect?: () => void;
+	/** Called when an error occurs */
+	onError?: (error: Error) => void;
+	/** Called when a message is received */
+	onMessage?: MessageHandler<TOutput>;
+}
+
+/**
+ * Options for EventStreamManager
+ */
+export interface EventStreamManagerOptions<TOutput = unknown> {
+	/** EventStream URL */
+	url: string;
+	/** Callbacks for state changes */
+	callbacks?: EventStreamCallbacks<TOutput>;
+	/** Reconnection configuration */
+	reconnect?: {
+		threshold?: number;
+		baseDelay?: number;
+		factor?: number;
+		maxDelay?: number;
+		jitter?: number;
+	};
+}
+
+/**
+ * EventStream manager state
+ */
+export interface EventStreamManagerState {
+	/** Whether EventStream is currently connected */
+	isConnected: boolean;
+	/** Current error, if any */
+	error: Error | null;
+	/** EventStream ready state */
+	readyState: number;
+}
+
+/**
+ * Generic EventStream (SSE) connection manager with automatic reconnection
+ * and handler management.
+ *
+ * Framework-agnostic - can be used with React, Svelte, Vue, or vanilla JS.
+ */
+export class EventStreamManager<TOutput = unknown> {
+	private es: EventSource | undefined;
+	private manualClose = false;
+	private pendingMessages: TOutput[] = [];
+	private messageHandler: MessageHandler<TOutput> | undefined;
+	private reconnectManager: ReconnectManager | undefined;
+	private callbacks: EventStreamCallbacks<TOutput>;
+	private url: string;
+	private reconnectConfig: Required<NonNullable<EventStreamManagerOptions<TOutput>['reconnect']>>;
+	private firstMessageReceived = false;
+
+	constructor(options: EventStreamManagerOptions<TOutput>) {
+		this.url = options.url;
+		this.callbacks = options.callbacks || {};
+		this.reconnectConfig = {
+			threshold: options.reconnect?.threshold ?? 3,
+			baseDelay: options.reconnect?.baseDelay ?? 500,
+			factor: options.reconnect?.factor ?? 2,
+			maxDelay: options.reconnect?.maxDelay ?? 30000,
+			jitter: options.reconnect?.jitter ?? 250,
+		};
+	}
+
+	/**
+	 * Connect to the EventStream server
+	 */
+	connect(): void {
+		if (this.manualClose) return;
+
+		this.es = new EventSource(this.url);
+		this.firstMessageReceived = false;
+
+		this.es.onopen = () => {
+			this.reconnectManager?.recordSuccess();
+			this.callbacks.onConnect?.();
+		};
+
+		this.es.onerror = () => {
+			const error = new Error('EventStream error');
+			this.callbacks.onError?.(error);
+			this.callbacks.onDisconnect?.();
+
+			if (this.manualClose) {
+				return;
+			}
+
+			const result = this.reconnectManager?.recordFailure();
+			if (result?.scheduled) {
+				// Close current connection before reconnecting
+				if (this.es) {
+					this.es.onopen = null;
+					this.es.onerror = null;
+					this.es.onmessage = null;
+					this.es.close();
+				}
+				this.es = undefined;
+			}
+		};
+
+		this.es.onmessage = (event: MessageEvent) => {
+			// Record success on first message (not just on open)
+			if (!this.firstMessageReceived) {
+				this.reconnectManager?.recordSuccess();
+				this.firstMessageReceived = true;
+			}
+
+			const payload = deserializeData<TOutput>(event.data);
+
+			// Call the registered message handler
+			if (this.messageHandler) {
+				this.messageHandler(payload);
+			} else {
+				// Buffer messages until a handler is set
+				this.pendingMessages.push(payload);
+			}
+
+			// Also call the callback if provided
+			this.callbacks.onMessage?.(payload);
+		};
+
+		// Setup reconnect manager
+		if (!this.reconnectManager) {
+			this.reconnectManager = createReconnectManager({
+				onReconnect: () => this.connect(),
+				threshold: this.reconnectConfig.threshold,
+				baseDelay: this.reconnectConfig.baseDelay,
+				factor: this.reconnectConfig.factor,
+				maxDelay: this.reconnectConfig.maxDelay,
+				jitter: this.reconnectConfig.jitter,
+				enabled: () => !this.manualClose,
+			});
+		}
+	}
+
+	/**
+	 * Set the message handler.
+	 * Any buffered messages will be delivered immediately.
+	 */
+	setMessageHandler(handler: MessageHandler<TOutput>): void {
+		this.messageHandler = handler;
+		// Flush pending messages
+		this.pendingMessages.forEach(handler);
+		this.pendingMessages = [];
+	}
+
+	/**
+	 * Get current state
+	 */
+	getState(): EventStreamManagerState {
+		return {
+			isConnected: this.es?.readyState === EventSource.OPEN,
+			error: null, // Error state managed externally via callbacks
+			readyState: this.es?.readyState ?? EventSource.CLOSED,
+		};
+	}
+
+	/**
+	 * Close the EventStream connection and cleanup
+	 */
+	close(): void {
+		this.manualClose = true;
+		this.reconnectManager?.dispose();
+
+		if (this.es) {
+			this.es.onopen = null;
+			this.es.onerror = null;
+			this.es.onmessage = null;
+			this.es.close();
+		}
+
+		this.es = undefined;
+		this.messageHandler = undefined;
+		this.pendingMessages = [];
+
+		// Notify disconnect callback
+		this.callbacks.onDisconnect?.();
+	}
+
+	/**
+	 * Dispose of the manager (alias for close)
+	 */
+	dispose(): void {
+		this.close();
+	}
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export { getProcessEnv } from './env';
+export { buildUrl, defaultBaseUrl } from './url';
+export { deserializeData } from './serialization';
+export { createReconnectManager, type ReconnectOptions, type ReconnectManager } from './reconnect';
+export { type RouteRegistry, type WebSocketRouteRegistry, type SSERouteRegistry } from './types';
+export { jsonEqual } from './memo';
+export {
+	WebSocketManager,
+	type MessageHandler as WebSocketMessageHandler,
+	type WebSocketCallbacks,
+	type WebSocketManagerOptions,
+	type WebSocketManagerState,
+} from './websocket-manager';
+export {
+	EventStreamManager,
+	type MessageHandler as EventStreamMessageHandler,
+	type EventStreamCallbacks,
+	type EventStreamManagerOptions,
+	type EventStreamManagerState,
+} from './eventstream-manager';

package/src/memo.ts

@@ -0,0 +1,16 @@
+/**
+ * Simple JSON-based equality check for memoization.
+ * Compares stringified JSON to avoid deep equality overhead.
+ */
+export function jsonEqual<T>(a: T, b: T): boolean {
+	if (a === b) return true;
+	if (a === undefined || b === undefined) return false;
+	if (a === null || b === null) return a === b;
+
+	try {
+		return JSON.stringify(a) === JSON.stringify(b);
+	} catch {
+		// Fallback for non-serializable values
+		return false;
+	}
+}

package/src/reconnect.ts

@@ -0,0 +1,73 @@
+export interface ReconnectOptions {
+	onReconnect: () => void;
+	threshold?: number;
+	baseDelay?: number;
+	factor?: number;
+	maxDelay?: number;
+	jitter?: number;
+	enabled?: () => boolean;
+}
+
+export interface ReconnectManager {
+	recordFailure: () => { scheduled: boolean; delay: number | null };
+	recordSuccess: () => void;
+	cancel: () => void;
+	reset: () => void;
+	dispose: () => void;
+	getAttempts: () => number;
+}
+
+export function createReconnectManager(opts: ReconnectOptions): ReconnectManager {
+	let attempts = 0;
+	let timer: ReturnType<typeof setTimeout> | null = null;
+
+	const cancel = () => {
+		if (timer) {
+			clearTimeout(timer);
+			timer = null;
+		}
+	};
+
+	const reset = () => {
+		attempts = 0;
+		cancel();
+	};
+
+	const recordSuccess = () => reset();
+
+	const computeDelay = (attemptAfterThreshold: number) => {
+		const base = opts.baseDelay ?? 500;
+		const factor = opts.factor ?? 2;
+		const max = opts.maxDelay ?? 30000;
+		const jitterMax = opts.jitter ?? 250;
+		const backoff = Math.min(base * Math.pow(factor, attemptAfterThreshold), max);
+		const jitter = jitterMax > 0 ? Math.random() * jitterMax : 0;
+		return backoff + jitter;
+	};
+
+	const recordFailure = () => {
+		attempts += 1;
+		const threshold = opts.threshold ?? 0;
+		if (opts.enabled && !opts.enabled()) {
+			return { scheduled: false, delay: null };
+		}
+
+		if (attempts - threshold >= 0) {
+			const after = Math.max(0, attempts - threshold);
+			const delay = computeDelay(after);
+			cancel();
+			timer = setTimeout(() => {
+				if (opts.enabled && !opts.enabled()) return;
+				opts.onReconnect();
+			}, delay);
+			return { scheduled: true, delay };
+		}
+		return { scheduled: false, delay: null };
+	};
+
+	const dispose = () => cancel();
+
+	const getAttempts = () => attempts;
+
+	return { recordFailure, recordSuccess, cancel, reset, dispose, getAttempts };
+}

package/src/serialization.ts

@@ -0,0 +1,14 @@
+/**
+ * Deserialize data received from WebSocket or EventStream.
+ * Attempts to parse as JSON if the data looks like JSON, otherwise returns as-is.
+ */
+export const deserializeData = <T>(data: string): T => {
+	if (data) {
+		try {
+			return JSON.parse(data) as T;
+		} catch {
+			/* */
+		}
+	}
+	return data as T;
+};

package/src/types.ts

@@ -0,0 +1,29 @@
+/**
+ * Route registry containing all typed API routes in the application.
+ * Auto-generated by the build tool from routes that use validator() middleware.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface RouteRegistry {
+	// Will be augmented by generated code
+	// Format: 'METHOD /path': { inputSchema: ..., outputSchema: ..., stream?: boolean }
+}
+
+/**
+ * WebSocket route registry containing all typed WebSocket routes in the application.
+ * Auto-generated by the build tool from routes that use validator() middleware.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface WebSocketRouteRegistry {
+	// Will be augmented by generated code
+	// Format: '/path': { inputSchema: ..., outputSchema: ... }
+}
+
+/**
+ * SSE route registry containing all typed SSE routes in the application.
+ * Auto-generated by the build tool from routes that use validator() middleware.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface SSERouteRegistry {
+	// Will be augmented by generated code
+	// Format: '/path': { inputSchema: ..., outputSchema: ... }
+}