@agentuity/frontend 0.0.100 → 0.0.101

package/AGENTS.md

@@ -1,4 +1,4 @@
-# Agent Guidelines for @agentuity/web
+# Agent Guidelines for @agentuity/frontend
 
 ## Package Overview
 

package/README.md

@@ -1,4 +1,4 @@
-# @agentuity/web
+# @agentuity/frontend
 
 Generic web utilities for building Agentuity frontend applications. Provides framework-agnostic utilities for URL building, serialization, reconnection logic, and type definitions.
 
@@ -7,7 +7,7 @@ This package contains reusable JavaScript logic that can be shared across differ
 ## Installation
 
 ```bash
-npm install @agentuity/web
+npm install @agentuity/frontend
 ```
 
 ## Features
@@ -24,7 +24,7 @@ npm install @agentuity/web
 ### URL Building
 
 ```typescript
-import { buildUrl, defaultBaseUrl } from '@agentuity/web';
+import { buildUrl, defaultBaseUrl } from '@agentuity/frontend';
 
 const url = buildUrl(
 	'https://api.example.com',
@@ -38,7 +38,7 @@ const url = buildUrl(
 ### Reconnection Manager
 
 ```typescript
-import { createReconnectManager } from '@agentuity/web';
+import { createReconnectManager } from '@agentuity/frontend';
 
 const reconnect = createReconnectManager({
 	onReconnect: () => console.log('Reconnecting...'),
@@ -55,7 +55,7 @@ reconnect.recordFailure();
 ### Serialization
 
 ```typescript
-import { deserializeData } from '@agentuity/web';
+import { deserializeData } from '@agentuity/frontend';
 
 const data = deserializeData<MyType>('{"key":"value"}');
 ```

package/dist/client/eventstream.d.ts

@@ -0,0 +1,12 @@
+import type { EventStreamClient } from './types';
+/**
+ * Create an EventSource (SSE) client wrapper with event-based API.
+ *
+ * Note: Native EventSource has limited authentication support.
+ * - withCredentials: true will send cookies and HTTP auth headers
+ * - For custom Authorization headers, consider using @microsoft/fetch-event-source
+ */
+export declare function createEventStreamClient(url: string, options?: {
+    withCredentials?: boolean;
+}): EventStreamClient;
+//# sourceMappingURL=eventstream.d.ts.map

package/dist/client/eventstream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventstream.d.ts","sourceRoot":"","sources":["../../src/client/eventstream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACtC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,GACrC,iBAAiB,CAuCnB"}

package/dist/client/eventstream.js

@@ -0,0 +1,39 @@
+/**
+ * Create an EventSource (SSE) client wrapper with event-based API.
+ *
+ * Note: Native EventSource has limited authentication support.
+ * - withCredentials: true will send cookies and HTTP auth headers
+ * - For custom Authorization headers, consider using @microsoft/fetch-event-source
+ */
+export function createEventStreamClient(url, options) {
+    const eventSource = new EventSource(url, {
+        withCredentials: options?.withCredentials ?? false,
+    });
+    const handlers = {
+        message: new Set(),
+        open: new Set(),
+        error: new Set(),
+    };
+    // Set up native EventSource event listeners
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    eventSource.onmessage = (event) => {
+        handlers.message.forEach((handler) => handler(event));
+    };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    eventSource.onopen = (event) => {
+        handlers.open.forEach((handler) => handler(event));
+    };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    eventSource.onerror = (event) => {
+        handlers.error.forEach((handler) => handler(event));
+    };
+    return {
+        on: ((event, handler) => {
+            handlers[event].add(handler);
+        }),
+        close() {
+            eventSource.close();
+        },
+    };
+}
+//# sourceMappingURL=eventstream.js.map

package/dist/client/eventstream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventstream.js","sourceRoot":"","sources":["../../src/client/eventstream.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACtC,GAAW,EACX,OAAuC;IAEvC,MAAM,WAAW,GAAG,IAAI,WAAW,CAAC,GAAG,EAAE;QACxC,eAAe,EAAE,OAAO,EAAE,eAAe,IAAI,KAAK;KAClD,CAAC,CAAC;IACH,MAAM,QAAQ,GAIV;QACH,OAAO,EAAE,IAAI,GAAG,EAAE;QAClB,IAAI,EAAE,IAAI,GAAG,EAAE;QACf,KAAK,EAAE,IAAI,GAAG,EAAE;KAChB,CAAC;IAEF,4CAA4C;IAC5C,8DAA8D;IAC9D,WAAW,CAAC,SAAS,GAAG,CAAC,KAAU,EAAE,EAAE;QACtC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACvD,CAAC,CAAC;IAEF,8DAA8D;IAC9D,WAAW,CAAC,MAAM,GAAG,CAAC,KAAU,EAAE,EAAE;QACnC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACpD,CAAC,CAAC;IAEF,8DAA8D;IAC9D,WAAW,CAAC,OAAO,GAAG,CAAC,KAAU,EAAE,EAAE;QACpC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACrD,CAAC,CAAC;IAEF,OAAO;QACN,EAAE,EAAE,CAAC,CAAC,KAAmC,EAAE,OAAqB,EAAE,EAAE;YACnE,QAAQ,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC,CAA4B;QAE7B,KAAK;YACJ,WAAW,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/client/index.d.ts

@@ -0,0 +1,33 @@
+import type { Client, ClientOptions } from './types';
+/**
+ * Create a type-safe API client from a RouteRegistry.
+ *
+ * Uses a Proxy to build up the path as you navigate the object,
+ * then executes the request when you call a terminal method (.post(), .get(), .websocket(), etc.).
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@agentuity/frontend';
+ * import type { RPCRouteRegistry } from './generated/routes';
+ *
+ * const client = createClient<RPCRouteRegistry>();
+ *
+ * // Type-safe API call
+ * const result = await client.hello.post({ name: 'World' });
+ *
+ * // WebSocket
+ * const ws = client.chat.websocket();
+ * ws.on('message', (msg) => console.log(msg));
+ *
+ * // Server-Sent Events
+ * const es = client.events.eventstream();
+ * es.on('message', (event) => console.log(event.data));
+ *
+ * // Streaming response
+ * const stream = await client.data.stream({ query: 'foo' });
+ * stream.on('chunk', (chunk) => console.log(chunk));
+ * ```
+ */
+export declare function createClient<R>(options?: ClientOptions, metadata?: unknown): Client<R>;
+export type { ClientOptions, Client, RouteEndpoint, WebSocketClient, EventStreamClient, StreamClient, EventHandler, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AA0BrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAE,aAAkB,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,CAwG1F;AAGD,YAAY,EACX,aAAa,EACb,MAAM,EACN,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,YAAY,GACZ,MAAM,SAAS,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,149 @@
+import { createWebSocketClient } from './websocket';
+import { createEventStreamClient } from './eventstream';
+import { createStreamClient } from './stream';
+/**
+ * Default base URL (empty = relative URLs).
+ */
+const defaultBaseUrl = '';
+/**
+ * Resolve baseUrl - if it's a function, call it; otherwise return the string.
+ */
+function resolveBaseUrl(baseUrl) {
+    return typeof baseUrl === 'function' ? baseUrl() : baseUrl;
+}
+/**
+ * Resolve headers - if it's a function, call it; otherwise return the object.
+ */
+function resolveHeaders(headers) {
+    return typeof headers === 'function' ? headers() : headers;
+}
+/**
+ * Create a type-safe API client from a RouteRegistry.
+ *
+ * Uses a Proxy to build up the path as you navigate the object,
+ * then executes the request when you call a terminal method (.post(), .get(), .websocket(), etc.).
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@agentuity/frontend';
+ * import type { RPCRouteRegistry } from './generated/routes';
+ *
+ * const client = createClient<RPCRouteRegistry>();
+ *
+ * // Type-safe API call
+ * const result = await client.hello.post({ name: 'World' });
+ *
+ * // WebSocket
+ * const ws = client.chat.websocket();
+ * ws.on('message', (msg) => console.log(msg));
+ *
+ * // Server-Sent Events
+ * const es = client.events.eventstream();
+ * es.on('message', (event) => console.log(event.data));
+ *
+ * // Streaming response
+ * const stream = await client.data.stream({ query: 'foo' });
+ * stream.on('chunk', (chunk) => console.log(chunk));
+ * ```
+ */
+export function createClient(options = {}, metadata) {
+    const { baseUrl = defaultBaseUrl, headers, contentType = 'application/json', signal } = options;
+    // Default headers to empty object if not provided
+    const defaultHeaders = headers || {};
+    const handler = {
+        get(target, prop) {
+            const currentPath = target.__path;
+            const newPath = [...currentPath, prop];
+            // Check if this is a terminal method
+            const httpMethods = ['get', 'post', 'put', 'delete', 'patch', 'head', 'options'];
+            const streamMethods = ['websocket', 'eventstream', 'stream'];
+            const isHttpMethod = httpMethods.includes(prop);
+            const isStreamMethod = streamMethods.includes(prop);
+            const isTerminalMethod = isHttpMethod || isStreamMethod;
+            // Terminal: method at the end (minimum 1 path segment required)
+            // Examples: client.hello.post(), client.echo.websocket(), client.events.eventstream()
+            if (isTerminalMethod && currentPath.length >= 1) {
+                const method = prop;
+                const pathSegments = currentPath;
+                const urlPath = '/api/' + pathSegments.join('/');
+                // Determine route type
+                let routeType = 'api';
+                if (isStreamMethod) {
+                    // Stream methods directly specify the route type
+                    if (method === 'websocket')
+                        routeType = 'websocket';
+                    else if (method === 'eventstream')
+                        routeType = 'sse';
+                    else if (method === 'stream')
+                        routeType = 'stream';
+                }
+                else if (metadata) {
+                    // Look up route type from metadata for HTTP methods
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    let metaNode = metadata;
+                    for (const segment of pathSegments) {
+                        if (metaNode && typeof metaNode === 'object') {
+                            metaNode = metaNode[segment];
+                        }
+                    }
+                    if (metaNode && typeof metaNode === 'object' && metaNode[method]?.type) {
+                        routeType = metaNode[method].type;
+                    }
+                }
+                return (input) => {
+                    const resolvedBaseUrl = resolveBaseUrl(baseUrl);
+                    const resolvedHeaders = resolveHeaders(defaultHeaders);
+                    // WebSocket endpoint
+                    if (routeType === 'websocket') {
+                        const wsBaseUrl = resolvedBaseUrl.replace(/^http/, 'ws');
+                        const wsUrl = `${wsBaseUrl}${urlPath}`;
+                        const ws = createWebSocketClient(wsUrl);
+                        if (input) {
+                            ws.on('open', () => ws.send(input));
+                        }
+                        return ws;
+                    }
+                    // SSE endpoint
+                    if (routeType === 'sse') {
+                        const sseUrl = `${resolvedBaseUrl}${urlPath}`;
+                        // Note: Native EventSource doesn't support custom headers
+                        // For auth, use withCredentials or consider fetch-based alternatives like @microsoft/fetch-event-source
+                        return createEventStreamClient(sseUrl, {
+                            withCredentials: Object.keys(resolvedHeaders).length > 0,
+                        });
+                    }
+                    // Stream endpoint
+                    if (routeType === 'stream') {
+                        return fetch(`${resolvedBaseUrl}${urlPath}`, {
+                            method: method.toUpperCase(),
+                            headers: { 'Content-Type': contentType, ...resolvedHeaders },
+                            body: input ? JSON.stringify(input) : undefined,
+                            signal,
+                        }).then((res) => {
+                            if (!res.ok)
+                                throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+                            return createStreamClient(res);
+                        });
+                    }
+                    // Regular API endpoint
+                    return fetch(`${resolvedBaseUrl}${urlPath}`, {
+                        method: method.toUpperCase(),
+                        headers: { 'Content-Type': contentType, ...resolvedHeaders },
+                        body: method.toUpperCase() !== 'GET' && input ? JSON.stringify(input) : undefined,
+                        signal,
+                    }).then(async (res) => {
+                        if (!res.ok)
+                            throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+                        if (res.status === 204)
+                            return undefined;
+                        return res.json();
+                    });
+                };
+            }
+            // Otherwise, return a new proxy with extended path
+            return new Proxy({ __path: newPath }, handler);
+        },
+    };
+    return new Proxy({ __path: [] }, handler);
+}
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

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

package/dist/client/stream.d.ts

@@ -0,0 +1,6 @@
+import type { StreamClient } from './types';
+/**
+ * Create a streaming response reader with event-based API.
+ */
+export declare function createStreamClient(response: Response): StreamClient;
+//# sourceMappingURL=stream.d.ts.map

package/dist/client/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/client/stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1D;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,YAAY,CAuDnE"}

package/dist/client/stream.js

@@ -0,0 +1,49 @@
+/**
+ * Create a streaming response reader with event-based API.
+ */
+export function createStreamClient(response) {
+    const handlers = {
+        chunk: new Set(),
+        close: new Set(),
+        error: new Set(),
+    };
+    const reader = response.body?.getReader();
+    let cancelled = false;
+    // Start reading the stream
+    const readStream = async () => {
+        if (!reader) {
+            const error = new Error('Response body is not readable');
+            handlers.error.forEach((handler) => handler(error));
+            return;
+        }
+        try {
+            while (!cancelled) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    handlers.close.forEach((handler) => handler());
+                    break;
+                }
+                if (value) {
+                    handlers.chunk.forEach((handler) => handler(value));
+                }
+            }
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            handlers.error.forEach((handler) => handler(err));
+        }
+    };
+    // Start reading immediately
+    readStream();
+    return {
+        on: ((event, handler) => {
+            handlers[event].add(handler);
+        }),
+        async cancel() {
+            cancelled = true;
+            await reader?.cancel();
+            handlers.close.forEach((handler) => handler());
+        },
+    };
+}
+//# sourceMappingURL=stream.js.map

package/dist/client/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/client/stream.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAkB;IACpD,MAAM,QAAQ,GAIV;QACH,KAAK,EAAE,IAAI,GAAG,EAAE;QAChB,KAAK,EAAE,IAAI,GAAG,EAAE;QAChB,KAAK,EAAE,IAAI,GAAG,EAAE;KAChB,CAAC;IAEF,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC;IAC1C,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,2BAA2B;IAC3B,MAAM,UAAU,GAAG,KAAK,IAAI,EAAE;QAC7B,IAAI,CAAC,MAAM,EAAE,CAAC;YACb,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;YACzD,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;YACpD,OAAO;QACR,CAAC;QAED,IAAI,CAAC;YACJ,OAAO,CAAC,SAAS,EAAE,CAAC;gBACnB,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;gBAE5C,IAAI,IAAI,EAAE,CAAC;oBACV,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;oBAC/C,MAAM;gBACP,CAAC;gBAED,IAAI,KAAK,EAAE,CAAC;oBACX,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;gBACrD,CAAC;YACF,CAAC;QACF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACtE,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QACnD,CAAC;IACF,CAAC,CAAC;IAEF,4BAA4B;IAC5B,UAAU,EAAE,CAAC;IAEb,OAAO;QACN,EAAE,EAAE,CAAC,CAAC,KAAkC,EAAE,OAAqB,EAAE,EAAE;YAClE,QAAQ,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,OAAkD,CAAC,CAAC;QACzE,CAAC,CAAuB;QAExB,KAAK,CAAC,MAAM;YACX,SAAS,GAAG,IAAI,CAAC;YACjB,MAAM,MAAM,EAAE,MAAM,EAAE,CAAC;YACvB,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;QAChD,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/client/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Type-safe API client types for RPC-style invocations.
+ */
+/**
+ * Options for creating a client.
+ */
+export interface ClientOptions {
+    /**
+     * Base URL for API requests (e.g., "https://p1234567890.agenuity.run").
+     * Defaults to empty string (relative URLs).
+     * Can be a string or a function that returns a string for lazy resolution.
+     */
+    baseUrl?: string | (() => string);
+    /**
+     * Default headers to include in all requests.
+     * Can be a static object or a function that returns headers for dynamic resolution (e.g., auth tokens).
+     */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /**
+     * Content-Type header for request bodies.
+     * @default "application/json"
+     */
+    contentType?: string;
+    /**
+     * AbortSignal for request cancellation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Event handler for streaming responses.
+ */
+export type EventHandler<T = unknown> = (data: T) => void;
+/**
+ * WebSocket wrapper with event-based API.
+ */
+export interface WebSocketClient {
+    /**
+     * Register an event handler.
+     */
+    on: {
+        (event: 'message', handler: EventHandler<unknown>): void;
+        (event: 'open', handler: EventHandler<Event>): void;
+        (event: 'close', handler: EventHandler<CloseEvent>): void;
+        (event: 'error', handler: EventHandler<Event>): void;
+    };
+    /**
+     * Send data through the WebSocket.
+     */
+    send(data: unknown): void;
+    /**
+     * Close the WebSocket connection.
+     */
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Server-Sent Events (SSE) client with event-based API.
+ */
+export interface EventStreamClient {
+    /**
+     * Register an event handler.
+     */
+    on: {
+        (event: 'message', handler: EventHandler<MessageEvent>): void;
+        (event: 'open', handler: EventHandler<Event>): void;
+        (event: 'error', handler: EventHandler<Event>): void;
+    };
+    /**
+     * Close the EventSource connection.
+     */
+    close(): void;
+}
+/**
+ * Streaming response reader with event-based API.
+ */
+export interface StreamClient {
+    /**
+     * Register an event handler.
+     */
+    on: {
+        (event: 'chunk', handler: EventHandler<Uint8Array>): void;
+        (event: 'close', handler: EventHandler<void>): void;
+        (event: 'error', handler: EventHandler<Error>): void;
+    };
+    /**
+     * Cancel the stream.
+     */
+    cancel(): Promise<void>;
+}
+/**
+ * API endpoint - callable function for regular HTTP calls.
+ */
+export type APIEndpoint<Input = unknown, Output = unknown> = (input?: Input) => Promise<Output>;
+/**
+ * WebSocket endpoint - callable function that returns WebSocket client.
+ */
+export type WebSocketEndpoint<Input = unknown, _Output = unknown> = (input?: Input) => WebSocketClient;
+/**
+ * Server-Sent Events endpoint - callable function that returns EventStream client.
+ */
+export type SSEEndpoint<Input = unknown, _Output = unknown> = (input?: Input) => EventStreamClient;
+/**
+ * Streaming endpoint - callable function that returns Stream client.
+ */
+export type StreamEndpoint<Input = unknown, _Output = unknown> = (input?: Input) => StreamClient;
+/**
+ * Route endpoint - discriminated union based on route type.
+ */
+export type RouteEndpoint<Input = unknown, Output = unknown, Type extends string = 'api'> = Type extends 'websocket' ? WebSocketEndpoint<Input, Output> : Type extends 'sse' ? SSEEndpoint<Input, Output> : Type extends 'stream' ? StreamEndpoint<Input, Output> : APIEndpoint<Input, Output>;
+/**
+ * Recursively build the client proxy type from a RouteRegistry.
+ */
+export type Client<R> = {
+    [K in keyof R]: R[K] extends {
+        input: infer I;
+        output: infer O;
+        type: infer T;
+    } ? RouteEndpoint<I, O, T extends string ? T : 'api'> : R[K] extends {
+        input: infer I;
+        output: infer O;
+    } ? RouteEndpoint<I, O, 'api'> : R[K] extends object ? Client<R[K]> : never;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/client/types.d.ts.map

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

package/dist/client/types.js

@@ -0,0 +1,5 @@
+/**
+ * Type-safe API client types for RPC-style invocations.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/client/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/client/websocket.d.ts

@@ -0,0 +1,6 @@
+import type { WebSocketClient } from './types';
+/**
+ * Create a WebSocket client wrapper with event-based API.
+ */
+export declare function createWebSocketClient(url: string, protocols?: string | string[]): WebSocketClient;
+//# sourceMappingURL=websocket.d.ts.map

package/dist/client/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../src/client/websocket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,eAAe,EAAE,MAAM,SAAS,CAAC;AAE7D;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,eAAe,CAuDjG"}

package/dist/client/websocket.js

@@ -0,0 +1,49 @@
+/**
+ * Create a WebSocket client wrapper with event-based API.
+ */
+export function createWebSocketClient(url, protocols) {
+    const ws = new WebSocket(url, protocols);
+    const handlers = {
+        message: new Set(),
+        open: new Set(),
+        close: new Set(),
+        error: new Set(),
+    };
+    // Set up native WebSocket event listeners
+    ws.addEventListener('message', (event) => {
+        let data = event.data;
+        // Try to parse JSON if data is a string
+        if (typeof event.data === 'string') {
+            try {
+                data = JSON.parse(event.data);
+            }
+            catch {
+                // Keep as string if not valid JSON
+                data = event.data;
+            }
+        }
+        handlers.message.forEach((handler) => handler(data));
+    });
+    ws.addEventListener('open', (event) => {
+        handlers.open.forEach((handler) => handler(event));
+    });
+    ws.addEventListener('close', (event) => {
+        handlers.close.forEach((handler) => handler(event));
+    });
+    ws.addEventListener('error', (event) => {
+        handlers.error.forEach((handler) => handler(event));
+    });
+    return {
+        on: ((event, handler) => {
+            handlers[event].add(handler);
+        }),
+        send(data) {
+            const payload = typeof data === 'string' ? data : JSON.stringify(data);
+            ws.send(payload);
+        },
+        close(code, reason) {
+            ws.close(code, reason);
+        },
+    };
+}
+//# sourceMappingURL=websocket.js.map

package/dist/client/websocket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.js","sourceRoot":"","sources":["../../src/client/websocket.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW,EAAE,SAA6B;IAC/E,MAAM,EAAE,GAAG,IAAI,SAAS,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACzC,MAAM,QAAQ,GAKV;QACH,OAAO,EAAE,IAAI,GAAG,EAAE;QAClB,IAAI,EAAE,IAAI,GAAG,EAAE;QACf,KAAK,EAAE,IAAI,GAAG,EAAE;QAChB,KAAK,EAAE,IAAI,GAAG,EAAE;KAChB,CAAC;IAEF,0CAA0C;IAC1C,EAAE,CAAC,gBAAgB,CAAC,SAAS,EAAE,CAAC,KAAmB,EAAE,EAAE;QACtD,IAAI,IAAI,GAAY,KAAK,CAAC,IAAI,CAAC;QAC/B,wCAAwC;QACxC,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACpC,IAAI,CAAC;gBACJ,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;YAAC,MAAM,CAAC;gBACR,mCAAmC;gBACnC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;YACnB,CAAC;QACF,CAAC;QACD,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gBAAgB,CAAC,MAAM,EAAE,CAAC,KAAY,EAAE,EAAE;QAC5C,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,KAAiB,EAAE,EAAE;QAClD,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,KAAY,EAAE,EAAE;QAC7C,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;IAEH,OAAO;QACN,EAAE,EAAE,CAAC,CAAC,KAA6C,EAAE,OAAqB,EAAE,EAAE;YAC7E,QAAQ,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,OAAqD,CAAC,CAAC;QAC5E,CAAC,CAA0B;QAE3B,IAAI,CAAC,IAAa;YACjB,MAAM,OAAO,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACvE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAClB,CAAC;QAED,KAAK,CAAC,IAAa,EAAE,MAAe;YACnC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACxB,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -6,4 +6,6 @@ export { type RouteRegistry, type WebSocketRouteRegistry, type SSERouteRegistry
 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';
+export { createClient } from './client/index';
+export type { Client, ClientOptions, RouteEndpoint, WebSocketClient, EventStreamClient, StreamClient, EventHandler, } from './client/types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACnG,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACjG,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EACN,gBAAgB,EAChB,KAAK,cAAc,IAAI,uBAAuB,EAC9C,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,kBAAkB,EAClB,KAAK,cAAc,IAAI,yBAAyB,EAChD,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,GAC5B,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACnG,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACjG,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EACN,gBAAgB,EAChB,KAAK,cAAc,IAAI,uBAAuB,EAC9C,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,kBAAkB,EAClB,KAAK,cAAc,IAAI,yBAAyB,EAChD,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,GAC5B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EACX,MAAM,EACN,aAAa,EACb,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,YAAY,GACZ,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -5,4 +5,6 @@ export { createReconnectManager } from './reconnect';
 export { jsonEqual } from './memo';
 export { WebSocketManager, } from './websocket-manager';
 export { EventStreamManager, } from './eventstream-manager';
+// Export client implementation (local to this package)
+export { createClient } from './client/index';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAgD,MAAM,aAAa,CAAC;AAEnG,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EACN,gBAAgB,GAKhB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,kBAAkB,GAKlB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAgD,MAAM,aAAa,CAAC;AAEnG,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EACN,gBAAgB,GAKhB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,kBAAkB,GAKlB,MAAM,uBAAuB,CAAC;AAE/B,uDAAuD;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/frontend",
-	"version": "0.0.100",
+	"version": "0.0.101",
 	"license": "Apache-2.0",
 	"author": "Agentuity employees and contributors",
 	"type": "module",
@@ -25,9 +25,11 @@
 		"test": "bun test",
 		"prepublishOnly": "bun run clean && bun run build"
 	},
-	"dependencies": {},
+	"dependencies": {
+		"@agentuity/core": "0.0.101"
+	},
 	"devDependencies": {
-		"@agentuity/test-utils": "workspace:*",
+		"@agentuity/test-utils": "0.0.101",
 		"@types/bun": "latest",
 		"bun-types": "latest",
 		"typescript": "^5.9.0"

package/src/client/eventstream.ts

@@ -0,0 +1,52 @@
+import type { EventHandler, EventStreamClient } from './types';
+
+/**
+ * Create an EventSource (SSE) client wrapper with event-based API.
+ *
+ * Note: Native EventSource has limited authentication support.
+ * - withCredentials: true will send cookies and HTTP auth headers
+ * - For custom Authorization headers, consider using @microsoft/fetch-event-source
+ */
+export function createEventStreamClient(
+	url: string,
+	options?: { withCredentials?: boolean }
+): EventStreamClient {
+	const eventSource = new EventSource(url, {
+		withCredentials: options?.withCredentials ?? false,
+	});
+	const handlers: {
+		message: Set<EventHandler<MessageEvent>>;
+		open: Set<EventHandler<Event>>;
+		error: Set<EventHandler<Event>>;
+	} = {
+		message: new Set(),
+		open: new Set(),
+		error: new Set(),
+	};
+
+	// Set up native EventSource event listeners
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	eventSource.onmessage = (event: any) => {
+		handlers.message.forEach((handler) => handler(event));
+	};
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	eventSource.onopen = (event: any) => {
+		handlers.open.forEach((handler) => handler(event));
+	};
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	eventSource.onerror = (event: any) => {
+		handlers.error.forEach((handler) => handler(event));
+	};
+
+	return {
+		on: ((event: 'message' | 'open' | 'error', handler: EventHandler) => {
+			handlers[event].add(handler);
+		}) as EventStreamClient['on'],
+
+		close() {
+			eventSource.close();
+		},
+	};
+}

package/src/client/index.ts

@@ -0,0 +1,171 @@
+import type { Client, ClientOptions } from './types';
+import { createWebSocketClient } from './websocket';
+import { createEventStreamClient } from './eventstream';
+import { createStreamClient } from './stream';
+
+/**
+ * Default base URL (empty = relative URLs).
+ */
+const defaultBaseUrl = '';
+
+/**
+ * Resolve baseUrl - if it's a function, call it; otherwise return the string.
+ */
+function resolveBaseUrl(baseUrl: string | (() => string)): string {
+	return typeof baseUrl === 'function' ? baseUrl() : baseUrl;
+}
+
+/**
+ * Resolve headers - if it's a function, call it; otherwise return the object.
+ */
+function resolveHeaders(
+	headers: Record<string, string> | (() => Record<string, string>)
+): Record<string, string> {
+	return typeof headers === 'function' ? headers() : headers;
+}
+
+/**
+ * Create a type-safe API client from a RouteRegistry.
+ *
+ * Uses a Proxy to build up the path as you navigate the object,
+ * then executes the request when you call a terminal method (.post(), .get(), .websocket(), etc.).
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@agentuity/frontend';
+ * import type { RPCRouteRegistry } from './generated/routes';
+ *
+ * const client = createClient<RPCRouteRegistry>();
+ *
+ * // Type-safe API call
+ * const result = await client.hello.post({ name: 'World' });
+ *
+ * // WebSocket
+ * const ws = client.chat.websocket();
+ * ws.on('message', (msg) => console.log(msg));
+ *
+ * // Server-Sent Events
+ * const es = client.events.eventstream();
+ * es.on('message', (event) => console.log(event.data));
+ *
+ * // Streaming response
+ * const stream = await client.data.stream({ query: 'foo' });
+ * stream.on('chunk', (chunk) => console.log(chunk));
+ * ```
+ */
+export function createClient<R>(options: ClientOptions = {}, metadata?: unknown): Client<R> {
+	const { baseUrl = defaultBaseUrl, headers, contentType = 'application/json', signal } = options;
+
+	// Default headers to empty object if not provided
+	const defaultHeaders = headers || {};
+
+	const handler: ProxyHandler<{ __path: string[]; __type?: string }> = {
+		get(target, prop: string) {
+			const currentPath = target.__path;
+			const newPath = [...currentPath, prop];
+
+			// Check if this is a terminal method
+			const httpMethods = ['get', 'post', 'put', 'delete', 'patch', 'head', 'options'];
+			const streamMethods = ['websocket', 'eventstream', 'stream'];
+			const isHttpMethod = httpMethods.includes(prop);
+			const isStreamMethod = streamMethods.includes(prop);
+			const isTerminalMethod = isHttpMethod || isStreamMethod;
+
+			// Terminal: method at the end (minimum 1 path segment required)
+			// Examples: client.hello.post(), client.echo.websocket(), client.events.eventstream()
+			if (isTerminalMethod && currentPath.length >= 1) {
+				const method = prop;
+				const pathSegments = currentPath;
+				const urlPath = '/api/' + pathSegments.join('/');
+
+				// Determine route type
+				let routeType = 'api';
+				if (isStreamMethod) {
+					// Stream methods directly specify the route type
+					if (method === 'websocket') routeType = 'websocket';
+					else if (method === 'eventstream') routeType = 'sse';
+					else if (method === 'stream') routeType = 'stream';
+				} else if (metadata) {
+					// Look up route type from metadata for HTTP methods
+					// eslint-disable-next-line @typescript-eslint/no-explicit-any
+					let metaNode: any = metadata;
+					for (const segment of pathSegments) {
+						if (metaNode && typeof metaNode === 'object') {
+							metaNode = metaNode[segment];
+						}
+					}
+					if (metaNode && typeof metaNode === 'object' && metaNode[method]?.type) {
+						routeType = metaNode[method].type;
+					}
+				}
+
+				return (input?: unknown) => {
+					const resolvedBaseUrl = resolveBaseUrl(baseUrl);
+					const resolvedHeaders = resolveHeaders(defaultHeaders);
+
+					// WebSocket endpoint
+					if (routeType === 'websocket') {
+						const wsBaseUrl = resolvedBaseUrl.replace(/^http/, 'ws');
+						const wsUrl = `${wsBaseUrl}${urlPath}`;
+						const ws = createWebSocketClient(wsUrl);
+						if (input) {
+							ws.on('open', () => ws.send(input));
+						}
+						return ws;
+					}
+
+					// SSE endpoint
+					if (routeType === 'sse') {
+						const sseUrl = `${resolvedBaseUrl}${urlPath}`;
+						// Note: Native EventSource doesn't support custom headers
+						// For auth, use withCredentials or consider fetch-based alternatives like @microsoft/fetch-event-source
+						return createEventStreamClient(sseUrl, {
+							withCredentials: Object.keys(resolvedHeaders).length > 0,
+						});
+					}
+
+					// Stream endpoint
+					if (routeType === 'stream') {
+						return fetch(`${resolvedBaseUrl}${urlPath}`, {
+							method: method.toUpperCase(),
+							headers: { 'Content-Type': contentType, ...resolvedHeaders },
+							body: input ? JSON.stringify(input) : undefined,
+							signal,
+						}).then((res) => {
+							if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+							return createStreamClient(res);
+						});
+					}
+
+					// Regular API endpoint
+					return fetch(`${resolvedBaseUrl}${urlPath}`, {
+						method: method.toUpperCase(),
+						headers: { 'Content-Type': contentType, ...resolvedHeaders },
+						body: method.toUpperCase() !== 'GET' && input ? JSON.stringify(input) : undefined,
+						signal,
+					}).then(async (res) => {
+						if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+						if (res.status === 204) return undefined;
+						return res.json();
+					});
+				};
+			}
+
+			// Otherwise, return a new proxy with extended path
+			return new Proxy({ __path: newPath }, handler);
+		},
+	};
+
+	return new Proxy({ __path: [] }, handler) as unknown as Client<R>;
+}
+
+// Re-export types
+export type {
+	ClientOptions,
+	Client,
+	RouteEndpoint,
+	WebSocketClient,
+	EventStreamClient,
+	StreamClient,
+	EventHandler,
+} from './types';

package/src/client/stream.ts

@@ -0,0 +1,61 @@
+import type { EventHandler, StreamClient } from './types';
+
+/**
+ * Create a streaming response reader with event-based API.
+ */
+export function createStreamClient(response: Response): StreamClient {
+	const handlers: {
+		chunk: Set<EventHandler<Uint8Array>>;
+		close: Set<EventHandler<void>>;
+		error: Set<EventHandler<Error>>;
+	} = {
+		chunk: new Set(),
+		close: new Set(),
+		error: new Set(),
+	};
+
+	const reader = response.body?.getReader();
+	let cancelled = false;
+
+	// Start reading the stream
+	const readStream = async () => {
+		if (!reader) {
+			const error = new Error('Response body is not readable');
+			handlers.error.forEach((handler) => handler(error));
+			return;
+		}
+
+		try {
+			while (!cancelled) {
+				const { done, value } = await reader.read();
+
+				if (done) {
+					handlers.close.forEach((handler) => handler());
+					break;
+				}
+
+				if (value) {
+					handlers.chunk.forEach((handler) => handler(value));
+				}
+			}
+		} catch (error) {
+			const err = error instanceof Error ? error : new Error(String(error));
+			handlers.error.forEach((handler) => handler(err));
+		}
+	};
+
+	// Start reading immediately
+	readStream();
+
+	return {
+		on: ((event: 'chunk' | 'close' | 'error', handler: EventHandler) => {
+			handlers[event].add(handler as EventHandler<Uint8Array | void | Error>);
+		}) as StreamClient['on'],
+
+		async cancel() {
+			cancelled = true;
+			await reader?.cancel();
+			handlers.close.forEach((handler) => handler());
+		},
+	};
+}

package/src/client/types.ts

@@ -0,0 +1,150 @@
+/**
+ * Type-safe API client types for RPC-style invocations.
+ */
+
+/**
+ * Options for creating a client.
+ */
+export interface ClientOptions {
+	/**
+	 * Base URL for API requests (e.g., "https://p1234567890.agenuity.run").
+	 * Defaults to empty string (relative URLs).
+	 * Can be a string or a function that returns a string for lazy resolution.
+	 */
+	baseUrl?: string | (() => string);
+
+	/**
+	 * Default headers to include in all requests.
+	 * Can be a static object or a function that returns headers for dynamic resolution (e.g., auth tokens).
+	 */
+	headers?: Record<string, string> | (() => Record<string, string>);
+
+	/**
+	 * Content-Type header for request bodies.
+	 * @default "application/json"
+	 */
+	contentType?: string;
+
+	/**
+	 * AbortSignal for request cancellation.
+	 */
+	signal?: AbortSignal;
+}
+
+/**
+ * Event handler for streaming responses.
+ */
+export type EventHandler<T = unknown> = (data: T) => void;
+
+/**
+ * WebSocket wrapper with event-based API.
+ */
+export interface WebSocketClient {
+	/**
+	 * Register an event handler.
+	 */
+	on: {
+		(event: 'message', handler: EventHandler<unknown>): void;
+		(event: 'open', handler: EventHandler<Event>): void;
+		(event: 'close', handler: EventHandler<CloseEvent>): void;
+		(event: 'error', handler: EventHandler<Event>): void;
+	};
+
+	/**
+	 * Send data through the WebSocket.
+	 */
+	send(data: unknown): void;
+
+	/**
+	 * Close the WebSocket connection.
+	 */
+	close(code?: number, reason?: string): void;
+}
+
+/**
+ * Server-Sent Events (SSE) client with event-based API.
+ */
+export interface EventStreamClient {
+	/**
+	 * Register an event handler.
+	 */
+	on: {
+		(event: 'message', handler: EventHandler<MessageEvent>): void;
+		(event: 'open', handler: EventHandler<Event>): void;
+		(event: 'error', handler: EventHandler<Event>): void;
+	};
+
+	/**
+	 * Close the EventSource connection.
+	 */
+	close(): void;
+}
+
+/**
+ * Streaming response reader with event-based API.
+ */
+export interface StreamClient {
+	/**
+	 * Register an event handler.
+	 */
+	on: {
+		(event: 'chunk', handler: EventHandler<Uint8Array>): void;
+		(event: 'close', handler: EventHandler<void>): void;
+		(event: 'error', handler: EventHandler<Error>): void;
+	};
+
+	/**
+	 * Cancel the stream.
+	 */
+	cancel(): Promise<void>;
+}
+
+/**
+ * API endpoint - callable function for regular HTTP calls.
+ */
+export type APIEndpoint<Input = unknown, Output = unknown> = (input?: Input) => Promise<Output>;
+
+/**
+ * WebSocket endpoint - callable function that returns WebSocket client.
+ */
+export type WebSocketEndpoint<Input = unknown, _Output = unknown> = (
+	input?: Input
+) => WebSocketClient;
+
+/**
+ * Server-Sent Events endpoint - callable function that returns EventStream client.
+ */
+export type SSEEndpoint<Input = unknown, _Output = unknown> = (input?: Input) => EventStreamClient;
+
+/**
+ * Streaming endpoint - callable function that returns Stream client.
+ */
+export type StreamEndpoint<Input = unknown, _Output = unknown> = (input?: Input) => StreamClient;
+
+/**
+ * Route endpoint - discriminated union based on route type.
+ */
+export type RouteEndpoint<
+	Input = unknown,
+	Output = unknown,
+	Type extends string = 'api',
+> = Type extends 'websocket'
+	? WebSocketEndpoint<Input, Output>
+	: Type extends 'sse'
+		? SSEEndpoint<Input, Output>
+		: Type extends 'stream'
+			? StreamEndpoint<Input, Output>
+			: APIEndpoint<Input, Output>;
+
+/**
+ * Recursively build the client proxy type from a RouteRegistry.
+ */
+export type Client<R> = {
+	[K in keyof R]: R[K] extends { input: infer I; output: infer O; type: infer T }
+		? RouteEndpoint<I, O, T extends string ? T : 'api'>
+		: R[K] extends { input: infer I; output: infer O }
+			? RouteEndpoint<I, O, 'api'>
+			: R[K] extends object
+				? Client<R[K]>
+				: never;
+};

package/src/client/websocket.ts

@@ -0,0 +1,61 @@
+import type { EventHandler, WebSocketClient } from './types';
+
+/**
+ * Create a WebSocket client wrapper with event-based API.
+ */
+export function createWebSocketClient(url: string, protocols?: string | string[]): WebSocketClient {
+	const ws = new WebSocket(url, protocols);
+	const handlers: {
+		message: Set<EventHandler<unknown>>;
+		open: Set<EventHandler<Event>>;
+		close: Set<EventHandler<CloseEvent>>;
+		error: Set<EventHandler<Event>>;
+	} = {
+		message: new Set(),
+		open: new Set(),
+		close: new Set(),
+		error: new Set(),
+	};
+
+	// Set up native WebSocket event listeners
+	ws.addEventListener('message', (event: MessageEvent) => {
+		let data: unknown = event.data;
+		// Try to parse JSON if data is a string
+		if (typeof event.data === 'string') {
+			try {
+				data = JSON.parse(event.data);
+			} catch {
+				// Keep as string if not valid JSON
+				data = event.data;
+			}
+		}
+		handlers.message.forEach((handler) => handler(data));
+	});
+
+	ws.addEventListener('open', (event: Event) => {
+		handlers.open.forEach((handler) => handler(event));
+	});
+
+	ws.addEventListener('close', (event: CloseEvent) => {
+		handlers.close.forEach((handler) => handler(event));
+	});
+
+	ws.addEventListener('error', (event: Event) => {
+		handlers.error.forEach((handler) => handler(event));
+	});
+
+	return {
+		on: ((event: 'message' | 'open' | 'close' | 'error', handler: EventHandler) => {
+			handlers[event].add(handler as EventHandler<unknown | Event | CloseEvent>);
+		}) as WebSocketClient['on'],
+
+		send(data: unknown) {
+			const payload = typeof data === 'string' ? data : JSON.stringify(data);
+			ws.send(payload);
+		},
+
+		close(code?: number, reason?: string) {
+			ws.close(code, reason);
+		},
+	};
+}

package/src/index.ts

@@ -18,3 +18,15 @@ export {
 	type EventStreamManagerOptions,
 	type EventStreamManagerState,
 } from './eventstream-manager';
+
+// Export client implementation (local to this package)
+export { createClient } from './client/index';
+export type {
+	Client,
+	ClientOptions,
+	RouteEndpoint,
+	WebSocketClient,
+	EventStreamClient,
+	StreamClient,
+	EventHandler,
+} from './client/types';