@fluxstack/live-client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,359 @@
+import { WebSocketMessage, WebSocketResponse, FileUploadCompleteResponse, BinaryChunkHeader } from '@fluxstack/live';
+
+/** Auth credentials to send during WebSocket connection */
+interface LiveAuthOptions {
+    /** JWT or opaque token */
+    token?: string;
+    /** Provider name (if multiple auth providers configured) */
+    provider?: string;
+    /** Additional credentials (publicKey, signature, etc.) */
+    [key: string]: unknown;
+}
+interface LiveConnectionOptions {
+    /** WebSocket URL. Auto-detected from window.location if omitted. */
+    url?: string;
+    /** Auth credentials to send on connection */
+    auth?: LiveAuthOptions;
+    /** Auto-connect on creation. Default: true */
+    autoConnect?: boolean;
+    /** Reconnect interval in ms. Default: 1000 */
+    reconnectInterval?: number;
+    /** Max reconnect attempts. Default: 5 */
+    maxReconnectAttempts?: number;
+    /** Heartbeat interval in ms. Default: 30000 */
+    heartbeatInterval?: number;
+    /** Enable debug logging. Default: false */
+    debug?: boolean;
+}
+interface LiveConnectionState {
+    connected: boolean;
+    connecting: boolean;
+    error: string | null;
+    connectionId: string | null;
+    authenticated: boolean;
+}
+type StateChangeCallback$1 = (state: LiveConnectionState) => void;
+type ComponentCallback = (message: WebSocketResponse) => void;
+/**
+ * Framework-agnostic WebSocket connection manager.
+ * Handles reconnection, heartbeat, request-response pattern, and message routing.
+ */
+declare class LiveConnection {
+    private ws;
+    private options;
+    private reconnectAttempts;
+    private reconnectTimeout;
+    private heartbeatInterval;
+    private componentCallbacks;
+    private pendingRequests;
+    private stateListeners;
+    private _state;
+    constructor(options?: LiveConnectionOptions);
+    get state(): LiveConnectionState;
+    /** Subscribe to connection state changes */
+    onStateChange(callback: StateChangeCallback$1): () => void;
+    private setState;
+    private getWebSocketUrl;
+    private log;
+    /** Generate unique request ID */
+    generateRequestId(): string;
+    /** Connect to WebSocket server */
+    connect(): void;
+    /** Disconnect from WebSocket server */
+    disconnect(): void;
+    /** Manual reconnect */
+    reconnect(): void;
+    private attemptReconnect;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private handleMessage;
+    /** Send message without waiting for response */
+    sendMessage(message: WebSocketMessage): Promise<void>;
+    /** Send message and wait for response */
+    sendMessageAndWait(message: WebSocketMessage, timeout?: number): Promise<WebSocketResponse>;
+    /** Send binary data and wait for response (for file uploads) */
+    sendBinaryAndWait(data: ArrayBuffer, requestId: string, timeout?: number): Promise<WebSocketResponse>;
+    /** Register a component message callback */
+    registerComponent(componentId: string, callback: ComponentCallback): () => void;
+    /** Unregister a component */
+    unregisterComponent(componentId: string): void;
+    /** Authenticate (or re-authenticate) the WebSocket connection */
+    authenticate(credentials: LiveAuthOptions): Promise<boolean>;
+    /** Get the raw WebSocket instance */
+    getWebSocket(): WebSocket | null;
+    /** Destroy the connection and clean up all resources */
+    destroy(): void;
+}
+
+interface LiveComponentOptions<TState = Record<string, any>> {
+    /** Initial state to merge with server defaults */
+    initialState?: Partial<TState>;
+    /** Room to join on mount */
+    room?: string;
+    /** User ID for component isolation */
+    userId?: string;
+    /** Auto-mount when connection is ready. Default: true */
+    autoMount?: boolean;
+    /** Enable debug logging. Default: false */
+    debug?: boolean;
+}
+type StateChangeCallback<TState> = (state: TState, delta: Partial<TState> | null) => void;
+type ErrorCallback = (error: string) => void;
+/**
+ * High-level handle for a live component instance.
+ * Manages mount lifecycle, state sync, and action calling.
+ * Framework-agnostic — works with vanilla JS, Vue, Svelte, etc.
+ */
+declare class LiveComponentHandle<TState extends Record<string, any> = Record<string, any>> {
+    private connection;
+    private componentName;
+    private options;
+    private _componentId;
+    private _state;
+    private _mounted;
+    private _mounting;
+    private _error;
+    private stateListeners;
+    private errorListeners;
+    private unregisterComponent;
+    private unsubConnection;
+    constructor(connection: LiveConnection, componentName: string, options?: LiveComponentOptions<TState>);
+    /** Current component state */
+    get state(): Readonly<TState>;
+    /** Server-assigned component ID (null before mount) */
+    get componentId(): string | null;
+    /** Whether the component has been mounted */
+    get mounted(): boolean;
+    /** Whether the component is currently mounting */
+    get mounting(): boolean;
+    /** Last error message */
+    get error(): string | null;
+    /** Mount the component on the server */
+    mount(): Promise<void>;
+    /** Unmount the component from the server */
+    unmount(): Promise<void>;
+    /** Destroy the handle and clean up all resources */
+    destroy(): void;
+    /**
+     * Call an action on the server component.
+     * Returns the action's return value.
+     */
+    call<R = any>(action: string, payload?: Record<string, any>): Promise<R>;
+    /**
+     * Subscribe to state changes.
+     * Callback receives the full new state and the delta (or null for full updates).
+     * Returns an unsubscribe function.
+     */
+    onStateChange(callback: StateChangeCallback<TState>): () => void;
+    /**
+     * Subscribe to errors.
+     * Returns an unsubscribe function.
+     */
+    onError(callback: ErrorCallback): () => void;
+    private handleServerMessage;
+    private notifyStateChange;
+    private notifyError;
+    private cleanup;
+    private log;
+}
+
+type EventHandler<T = any> = (data: T) => void;
+type Unsubscribe = () => void;
+/** Message from client to server */
+interface RoomClientMessage {
+    type: 'ROOM_JOIN' | 'ROOM_LEAVE' | 'ROOM_EMIT' | 'ROOM_STATE_GET' | 'ROOM_STATE_SET';
+    componentId: string;
+    roomId: string;
+    event?: string;
+    data?: any;
+    timestamp: number;
+}
+/** Message from server to client */
+interface RoomServerMessage {
+    type: 'ROOM_EVENT' | 'ROOM_STATE' | 'ROOM_SYSTEM' | 'ROOM_JOINED' | 'ROOM_LEFT';
+    componentId: string;
+    roomId: string;
+    event: string;
+    data: any;
+    timestamp: number;
+}
+/** Interface of an individual room handle */
+interface RoomHandle<TState = any, TEvents extends Record<string, any> = Record<string, any>> {
+    readonly id: string;
+    readonly joined: boolean;
+    readonly state: TState;
+    join: (initialState?: TState) => Promise<void>;
+    leave: () => Promise<void>;
+    emit: <K extends keyof TEvents>(event: K, data: TEvents[K]) => void;
+    on: <K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>) => Unsubscribe;
+    onSystem: (event: string, handler: EventHandler) => Unsubscribe;
+    setState: (updates: Partial<TState>) => void;
+}
+/** Proxy interface for $room - callable as function or object */
+interface RoomProxy<TState = any, TEvents extends Record<string, any> = Record<string, any>> {
+    (roomId: string): RoomHandle<TState, TEvents>;
+    readonly id: string | null;
+    readonly joined: boolean;
+    readonly state: TState;
+    join: (initialState?: TState) => Promise<void>;
+    leave: () => Promise<void>;
+    emit: <K extends keyof TEvents>(event: K, data: TEvents[K]) => void;
+    on: <K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>) => Unsubscribe;
+    onSystem: (event: string, handler: EventHandler) => Unsubscribe;
+    setState: (updates: Partial<TState>) => void;
+}
+interface RoomManagerOptions {
+    componentId: string | null;
+    defaultRoom?: string;
+    sendMessage: (msg: any) => void;
+    sendMessageAndWait: (msg: any, timeout?: number) => Promise<any>;
+    onMessage: (handler: (msg: RoomServerMessage) => void) => Unsubscribe;
+}
+/** Client-side room manager. Framework-agnostic. */
+declare class RoomManager<TState = any, TEvents extends Record<string, any> = Record<string, any>> {
+    private componentId;
+    private defaultRoom;
+    private rooms;
+    private handles;
+    private sendMessage;
+    private sendMessageAndWait;
+    private globalUnsubscribe;
+    constructor(options: RoomManagerOptions);
+    private handleServerMessage;
+    private getOrCreateRoom;
+    /** Create handle for a specific room (cached) */
+    createHandle(roomId: string): RoomHandle<TState, TEvents>;
+    /** Create the $room proxy */
+    createProxy(): RoomProxy<TState, TEvents>;
+    /** List of rooms currently joined */
+    getJoinedRooms(): string[];
+    /** Update componentId (when component mounts) */
+    setComponentId(id: string | null): void;
+    /** Cleanup */
+    destroy(): void;
+}
+
+interface AdaptiveChunkConfig {
+    minChunkSize: number;
+    maxChunkSize: number;
+    initialChunkSize: number;
+    targetLatency: number;
+    adjustmentFactor: number;
+    measurementWindow: number;
+}
+interface ChunkMetrics {
+    chunkIndex: number;
+    chunkSize: number;
+    startTime: number;
+    endTime: number;
+    latency: number;
+    throughput: number;
+    success: boolean;
+}
+declare class AdaptiveChunkSizer {
+    private config;
+    private currentChunkSize;
+    private metrics;
+    private consecutiveErrors;
+    private consecutiveSuccesses;
+    constructor(config?: Partial<AdaptiveChunkConfig>);
+    getChunkSize(): number;
+    recordChunkStart(_chunkIndex: number): number;
+    recordChunkComplete(chunkIndex: number, chunkSize: number, startTime: number, success: boolean): void;
+    private adjustUp;
+    private adjustDown;
+    getAverageThroughput(): number;
+    getStats(): {
+        currentChunkSize: number;
+        averageThroughput: number;
+        consecutiveSuccesses: number;
+        consecutiveErrors: number;
+        totalMeasurements: number;
+    };
+    reset(): void;
+}
+/**
+ * Creates a binary message with header + data
+ * Format: [4 bytes header length LE][JSON header][binary data]
+ */
+declare function createBinaryChunkMessage(header: BinaryChunkHeader, chunkData: Uint8Array): ArrayBuffer;
+interface ChunkedUploadOptions {
+    chunkSize?: number;
+    maxFileSize?: number;
+    allowedTypes?: string[];
+    sendMessageAndWait: (message: any, timeout?: number) => Promise<any>;
+    sendBinaryAndWait?: (data: ArrayBuffer, requestId: string, timeout?: number) => Promise<any>;
+    onProgress?: (progress: number, bytesUploaded: number, totalBytes: number) => void;
+    onComplete?: (response: FileUploadCompleteResponse) => void;
+    onError?: (error: string) => void;
+    adaptiveChunking?: boolean;
+    adaptiveConfig?: Partial<AdaptiveChunkConfig>;
+    useBinaryProtocol?: boolean;
+}
+interface ChunkedUploadState {
+    uploading: boolean;
+    progress: number;
+    error: string | null;
+    uploadId: string | null;
+    bytesUploaded: number;
+    totalBytes: number;
+}
+/**
+ * Framework-agnostic chunked file uploader.
+ * Manages the upload lifecycle without any UI framework dependency.
+ */
+declare class ChunkedUploader {
+    private componentId;
+    private options;
+    private abortController;
+    private adaptiveSizer;
+    private _state;
+    private stateListeners;
+    constructor(componentId: string, options: ChunkedUploadOptions);
+    get state(): ChunkedUploadState;
+    onStateChange(callback: (state: ChunkedUploadState) => void): () => void;
+    private setState;
+    uploadFile(file: File): Promise<void>;
+    cancelUpload(): void;
+    reset(): void;
+}
+
+interface PersistedState {
+    componentName: string;
+    signedState: any;
+    room?: string;
+    userId?: string;
+    lastUpdate: number;
+}
+declare function persistState(enabled: boolean, name: string, signedState: any, room?: string, userId?: string): void;
+declare function getPersistedState(enabled: boolean, name: string): PersistedState | null;
+declare function clearPersistedState(enabled: boolean, name: string): void;
+
+interface StateValidation {
+    checksum: string;
+    version: number;
+    timestamp: number;
+    source: 'client' | 'server' | 'mount';
+}
+interface StateConflict {
+    property: string;
+    clientValue: any;
+    serverValue: any;
+    timestamp: number;
+    resolved: boolean;
+}
+interface HybridState<T> {
+    data: T;
+    validation: StateValidation;
+    status: 'synced' | 'pending' | 'conflict';
+}
+declare class StateValidator {
+    static generateChecksum(state: any): string;
+    static createValidation(state: any, source?: 'client' | 'server' | 'mount'): StateValidation;
+    static detectConflicts<T>(clientState: T, serverState: T, excludeFields?: string[]): StateConflict[];
+    static mergeStates<T>(clientState: T, serverState: T, conflicts: StateConflict[], strategy?: 'client' | 'server' | 'smart'): T;
+    static validateState<T>(hybridState: HybridState<T>): boolean;
+    static updateValidation<T>(hybridState: HybridState<T>, source?: 'client' | 'server' | 'mount'): HybridState<T>;
+}
+
+export { type AdaptiveChunkConfig, AdaptiveChunkSizer, type ChunkMetrics, type ChunkedUploadOptions, type ChunkedUploadState, ChunkedUploader, type EventHandler, type HybridState, type LiveAuthOptions, LiveComponentHandle, type LiveComponentOptions, LiveConnection, type LiveConnectionOptions, type LiveConnectionState, type PersistedState, type RoomClientMessage, type RoomHandle, RoomManager, type RoomManagerOptions, type RoomProxy, type RoomServerMessage, type StateConflict, type StateValidation, StateValidator, type Unsubscribe, clearPersistedState, createBinaryChunkMessage, getPersistedState, persistState };