routeflow-api 0.2.0

package/dist/client/index.d.cts

@@ -0,0 +1,174 @@
+/**
+ * Options passed to `createClient`.
+ */
+interface ClientOptions {
+    /**
+     * Base URL of the RouteFlow server (e.g. 'http://localhost:3000').
+     * Trailing slash is trimmed automatically.
+     */
+    baseUrl: string;
+    /**
+     * Default headers added to every HTTP request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Real-time transport mechanism.
+     * - `'websocket'` (default) — uses WebSocket; full-duplex, supported everywhere.
+     * - `'sse'` — uses Server-Sent Events; simpler, works over plain HTTP/1.1.
+     */
+    transport?: 'websocket' | 'sse';
+    /**
+     * Reconnect / backoff settings for the real-time transport.
+     */
+    reconnect?: ReconnectOptions;
+    /**
+     * Global error handler called when the server sends an error message
+     * over the real-time channel, or when a subscription callback throws.
+     */
+    onError?: (error: {
+        code: string;
+        message: string;
+    }) => void;
+}
+/**
+ * Exponential-backoff reconnect configuration.
+ */
+interface ReconnectOptions {
+    /** Maximum number of reconnect attempts. 0 = unlimited. Default: 0 */
+    maxAttempts?: number;
+    /** Initial delay in ms before first retry. Default: 500 */
+    initialDelayMs?: number;
+    /** Multiplier applied to the delay on each failure. Default: 2 */
+    backoffFactor?: number;
+    /** Maximum delay cap in ms. Default: 30_000 */
+    maxDelayMs?: number;
+}
+/**
+ * Options passed to `subscribe()`.
+ */
+interface SubscribeOptions<T> {
+    /** Query string params forwarded with the subscription request. */
+    query?: Record<string, string>;
+    /** Called when the server sends an error for this subscription. */
+    onError?: (error: {
+        code: string;
+        message: string;
+    }) => void;
+    /** Called when the underlying connection closes unexpectedly. */
+    onClose?: () => void;
+    /** Called on each data update. Alias for the callback positional arg. */
+    onData?: SubscriptionCallback<T>;
+}
+/**
+ * Callback invoked when new data is pushed for a subscribed path.
+ */
+type SubscriptionCallback<T> = (data: T) => void;
+/**
+ * Call this function to cancel a subscription.
+ */
+type Unsubscribe = () => void;
+
+/**
+ * RouteFlow client.
+ *
+ * Provides:
+ * - HTTP helpers (`get`, `post`, `put`, `patch`, `del`) backed by the Fetch API
+ * - Real-time subscriptions (`subscribe`) via WebSocket or SSE
+ *
+ * Fully browser-compatible — no Node.js-specific APIs used.
+ *
+ * @example
+ * ```ts
+ * const client = createClient('http://localhost:3000')
+ *
+ * // One-off REST request
+ * const orders = await client.get<Order[]>('/orders/123')
+ *
+ * // Real-time subscription
+ * const unsubscribe = client.subscribe<Order[]>('/orders/123/live', (data) => {
+ *   console.log('updated:', data)
+ * })
+ *
+ * // Later…
+ * unsubscribe()
+ * client.destroy()
+ * ```
+ */
+declare class ReactiveClient {
+    private readonly baseUrl;
+    private readonly defaultHeaders;
+    private socket;
+    /** path → ReactiveSSE instance (one per path for SSE) */
+    private readonly sseStreams;
+    private readonly options;
+    constructor(options: ClientOptions);
+    /**
+     * Perform a GET request.
+     * @param path    - Path relative to baseUrl (e.g. '/orders/123')
+     * @param query   - Optional query string parameters
+     * @param headers - Per-request header overrides
+     */
+    get<T>(path: string, query?: Record<string, string>, headers?: Record<string, string>): Promise<T>;
+    /** Perform a POST request. */
+    post<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    /** Perform a PUT request. */
+    put<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    /** Perform a PATCH request. */
+    patch<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    /**
+     * Perform a DELETE request.
+     * Named `del` because `delete` is a reserved keyword.
+     */
+    del<T>(path: string, headers?: Record<string, string>): Promise<T>;
+    /**
+     * Subscribe to real-time updates pushed by the server for `path`.
+     *
+     * Uses WebSocket or SSE depending on the `transport` option passed to `createClient`.
+     *
+     * @param path     - The reactive endpoint path (e.g. '/orders/123/live')
+     * @param callback - Invoked with the latest data on each push
+     * @param query    - Optional query params forwarded in the subscription request
+     * @returns An unsubscribe function — call it to stop receiving updates.
+     */
+    subscribe<T>(path: string, callback: SubscriptionCallback<T>, query?: Record<string, string>): Unsubscribe;
+    /**
+     * Close the real-time transport and release all resources.
+     * Call this when the client is no longer needed (e.g. component unmount).
+     */
+    destroy(): void;
+    private subscribeWS;
+    private subscribeSSE;
+    private request;
+}
+/**
+ * Create a new RouteFlow client instance.
+ *
+ * @example
+ * ```ts
+ * // WebSocket (default)
+ * const client = createClient('http://localhost:3000')
+ *
+ * // SSE transport
+ * const client = createClient('http://localhost:3000', { transport: 'sse' })
+ *
+ * // With auth header and custom error handler
+ * const client = createClient('http://localhost:3000', {
+ *   headers: { Authorization: 'Bearer token' },
+ *   onError: (err) => console.error('realtime error:', err),
+ * })
+ * ```
+ */
+declare function createClient(baseUrl: string, options?: Omit<ClientOptions, 'baseUrl'>): ReactiveClient;
+
+/**
+ * Error thrown by the RouteFlow client for HTTP or WebSocket failures.
+ */
+declare class ReactiveClientError extends Error {
+    /** Machine-readable error code */
+    readonly code: string;
+    /** HTTP status code, if applicable */
+    readonly status?: number;
+    constructor(code: string, message: string, status?: number);
+}
+
+export { type ClientOptions, ReactiveClient, ReactiveClientError, type ReconnectOptions, type SubscribeOptions, type SubscriptionCallback, type Unsubscribe, createClient };

package/dist/client/index.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Options passed to `createClient`.
+ */
+interface ClientOptions {
+    /**
+     * Base URL of the RouteFlow server (e.g. 'http://localhost:3000').
+     * Trailing slash is trimmed automatically.
+     */
+    baseUrl: string;
+    /**
+     * Default headers added to every HTTP request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Real-time transport mechanism.
+     * - `'websocket'` (default) — uses WebSocket; full-duplex, supported everywhere.
+     * - `'sse'` — uses Server-Sent Events; simpler, works over plain HTTP/1.1.
+     */
+    transport?: 'websocket' | 'sse';
+    /**
+     * Reconnect / backoff settings for the real-time transport.
+     */
+    reconnect?: ReconnectOptions;
+    /**
+     * Global error handler called when the server sends an error message
+     * over the real-time channel, or when a subscription callback throws.
+     */
+    onError?: (error: {
+        code: string;
+        message: string;
+    }) => void;
+}
+/**
+ * Exponential-backoff reconnect configuration.
+ */
+interface ReconnectOptions {
+    /** Maximum number of reconnect attempts. 0 = unlimited. Default: 0 */
+    maxAttempts?: number;
+    /** Initial delay in ms before first retry. Default: 500 */
+    initialDelayMs?: number;
+    /** Multiplier applied to the delay on each failure. Default: 2 */
+    backoffFactor?: number;
+    /** Maximum delay cap in ms. Default: 30_000 */
+    maxDelayMs?: number;
+}
+/**
+ * Options passed to `subscribe()`.
+ */
+interface SubscribeOptions<T> {
+    /** Query string params forwarded with the subscription request. */
+    query?: Record<string, string>;
+    /** Called when the server sends an error for this subscription. */
+    onError?: (error: {
+        code: string;
+        message: string;
+    }) => void;
+    /** Called when the underlying connection closes unexpectedly. */
+    onClose?: () => void;
+    /** Called on each data update. Alias for the callback positional arg. */
+    onData?: SubscriptionCallback<T>;
+}
+/**
+ * Callback invoked when new data is pushed for a subscribed path.
+ */
+type SubscriptionCallback<T> = (data: T) => void;
+/**
+ * Call this function to cancel a subscription.
+ */
+type Unsubscribe = () => void;
+
+/**
+ * RouteFlow client.
+ *
+ * Provides:
+ * - HTTP helpers (`get`, `post`, `put`, `patch`, `del`) backed by the Fetch API
+ * - Real-time subscriptions (`subscribe`) via WebSocket or SSE
+ *
+ * Fully browser-compatible — no Node.js-specific APIs used.
+ *
+ * @example
+ * ```ts
+ * const client = createClient('http://localhost:3000')
+ *
+ * // One-off REST request
+ * const orders = await client.get<Order[]>('/orders/123')
+ *
+ * // Real-time subscription
+ * const unsubscribe = client.subscribe<Order[]>('/orders/123/live', (data) => {
+ *   console.log('updated:', data)
+ * })
+ *
+ * // Later…
+ * unsubscribe()
+ * client.destroy()
+ * ```
+ */
+declare class ReactiveClient {
+    private readonly baseUrl;
+    private readonly defaultHeaders;
+    private socket;
+    /** path → ReactiveSSE instance (one per path for SSE) */
+    private readonly sseStreams;
+    private readonly options;
+    constructor(options: ClientOptions);
+    /**
+     * Perform a GET request.
+     * @param path    - Path relative to baseUrl (e.g. '/orders/123')
+     * @param query   - Optional query string parameters
+     * @param headers - Per-request header overrides
+     */
+    get<T>(path: string, query?: Record<string, string>, headers?: Record<string, string>): Promise<T>;
+    /** Perform a POST request. */
+    post<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    /** Perform a PUT request. */
+    put<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    /** Perform a PATCH request. */
+    patch<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    /**
+     * Perform a DELETE request.
+     * Named `del` because `delete` is a reserved keyword.
+     */
+    del<T>(path: string, headers?: Record<string, string>): Promise<T>;
+    /**
+     * Subscribe to real-time updates pushed by the server for `path`.
+     *
+     * Uses WebSocket or SSE depending on the `transport` option passed to `createClient`.
+     *
+     * @param path     - The reactive endpoint path (e.g. '/orders/123/live')
+     * @param callback - Invoked with the latest data on each push
+     * @param query    - Optional query params forwarded in the subscription request
+     * @returns An unsubscribe function — call it to stop receiving updates.
+     */
+    subscribe<T>(path: string, callback: SubscriptionCallback<T>, query?: Record<string, string>): Unsubscribe;
+    /**
+     * Close the real-time transport and release all resources.
+     * Call this when the client is no longer needed (e.g. component unmount).
+     */
+    destroy(): void;
+    private subscribeWS;
+    private subscribeSSE;
+    private request;
+}
+/**
+ * Create a new RouteFlow client instance.
+ *
+ * @example
+ * ```ts
+ * // WebSocket (default)
+ * const client = createClient('http://localhost:3000')
+ *
+ * // SSE transport
+ * const client = createClient('http://localhost:3000', { transport: 'sse' })
+ *
+ * // With auth header and custom error handler
+ * const client = createClient('http://localhost:3000', {
+ *   headers: { Authorization: 'Bearer token' },
+ *   onError: (err) => console.error('realtime error:', err),
+ * })
+ * ```
+ */
+declare function createClient(baseUrl: string, options?: Omit<ClientOptions, 'baseUrl'>): ReactiveClient;
+
+/**
+ * Error thrown by the RouteFlow client for HTTP or WebSocket failures.
+ */
+declare class ReactiveClientError extends Error {
+    /** Machine-readable error code */
+    readonly code: string;
+    /** HTTP status code, if applicable */
+    readonly status?: number;
+    constructor(code: string, message: string, status?: number);
+}
+
+export { type ClientOptions, ReactiveClient, ReactiveClientError, type ReconnectOptions, type SubscribeOptions, type SubscriptionCallback, type Unsubscribe, createClient };