dialogue-ts 0.0.1

package/dist/client/index.d.cts

@@ -0,0 +1,273 @@
+import { Socket } from 'socket.io-client';
+
+/**
+ * Client-side type definitions for Dialogue
+ * These types mirror the backend types for consistent API
+ */
+/**
+ * Configuration for DialogueClient
+ */
+interface ClientConfig {
+    /** WebSocket server URL (e.g., 'ws://localhost:3000' or 'wss://example.com') */
+    url: string;
+    /** Authentication data sent with connection */
+    auth?: {
+        /** User ID for identification */
+        userId?: string;
+        /** JWT or other auth token */
+        token?: string;
+        /** Additional auth data */
+        [key: string]: unknown;
+    };
+    /** Auto-connect on instantiation (default: true) */
+    autoConnect?: boolean;
+    /** Reconnection options */
+    reconnection?: boolean;
+    /** Number of reconnection attempts */
+    reconnectionAttempts?: number;
+}
+/**
+ * Room info returned by listRooms
+ */
+interface RoomInfo {
+    id: string;
+    name: string;
+    description?: string;
+    size: number;
+    maxSize?: number;
+    createdById?: string;
+}
+/**
+ * Options for creating a room
+ */
+interface CreateRoomOptions {
+    /** Unique room identifier */
+    id: string;
+    /** Human-readable room name */
+    name: string;
+    /** Room description */
+    description?: string;
+    /** Maximum number of participants */
+    maxSize?: number;
+}
+/**
+ * Event message received from server
+ * Matches EventMessage from backend
+ */
+interface EventMessage<T = unknown> {
+    event: string;
+    roomId: string;
+    data: T;
+    from: string;
+    timestamp: number;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Error response from server
+ */
+interface DialogueError {
+    code: string;
+    message: string;
+}
+/**
+ * Connection result emitted on successful connect
+ */
+interface ConnectionResult {
+    clientId: string;
+    userId: string;
+}
+/**
+ * Room join result
+ */
+interface JoinResult {
+    roomId: string;
+    roomName: string;
+}
+/**
+ * Room context - represents a joined room with methods
+ */
+interface RoomContext {
+    /** Room ID */
+    readonly roomId: string;
+    /** Room name */
+    readonly roomName: string;
+    /**
+     * Trigger an event in this room
+     * @param eventName - Event name to trigger
+     * @param data - Event payload data
+     * @param meta - Optional metadata for flexible additional context
+     */
+    trigger<T>(eventName: string, data: T, meta?: Record<string, unknown>): void;
+    /**
+     * Listen for a specific event
+     * @param eventName - Event name to listen for
+     * @param handler - Callback when event received
+     * @returns Unsubscribe function
+     */
+    on<T>(eventName: string, handler: (msg: EventMessage<T>) => void): () => void;
+    /**
+     * Listen for all events in this room
+     * @param handler - Callback for any event
+     * @returns Unsubscribe function
+     */
+    onAny(handler: (eventName: string, msg: EventMessage<unknown>) => void): () => void;
+    /**
+     * Subscribe to additional event type
+     * @param eventName - Event name to subscribe to
+     */
+    subscribe(eventName: string): void;
+    /**
+     * Subscribe to all events in this room
+     * Tells the server to send all events from this room to this client
+     */
+    subscribeAll(): void;
+    /**
+     * Unsubscribe from event type
+     * @param eventName - Event name to unsubscribe from
+     */
+    unsubscribe(eventName: string): void;
+    /**
+     * Get historical events for this room (paginated, newest first)
+     * @param eventName - Event type to get history for
+     * @param start - Starting index (0 = most recent)
+     * @param end - Ending index (exclusive)
+     * @returns Promise resolving to array of events
+     */
+    getHistory<T = unknown>(eventName: string, start?: number, end?: number): Promise<EventMessage<T>[]>;
+    /**
+     * Leave this room
+     */
+    leave(): void;
+}
+/**
+ * Event handler type
+ */
+type EventHandler<T = unknown> = (msg: EventMessage<T>) => void;
+/**
+ * Wildcard event handler type
+ */
+type WildcardHandler = (eventName: string, msg: EventMessage<unknown>) => void;
+/**
+ * Connection state
+ */
+type ConnectionState = "disconnected" | "connecting" | "connected";
+
+/**
+ * Dialogue client instance returned by createDialogueClient
+ */
+interface DialogueClientInstance {
+    /** User ID assigned by the server */
+    readonly userId: string;
+    /** Whether the client is connected to the server */
+    readonly connected: boolean;
+    /** Current connection state */
+    readonly state: ConnectionState;
+    /**
+     * Connect to the server
+     * @returns Promise that resolves when connected
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the server
+     */
+    disconnect(): void;
+    /**
+     * Join a room
+     * @param roomId - Room ID to join
+     * @returns Promise resolving to RoomContext
+     */
+    join(roomId: string): Promise<RoomContext>;
+    /**
+     * Get a joined room context
+     * @param roomId - Room ID
+     * @returns RoomContext or undefined if not joined
+     */
+    getRoom(roomId: string): RoomContext | undefined;
+    /**
+     * List all available rooms on the server
+     * @returns Promise resolving to array of room info
+     */
+    listRooms(): Promise<RoomInfo[]>;
+    /**
+     * Create a new room on the server
+     * @param options - Room creation options
+     * @returns Promise resolving to created room info
+     */
+    createRoom(options: CreateRoomOptions): Promise<RoomInfo>;
+    /**
+     * Delete a room on the server (only creator can delete)
+     * @param roomId - Room ID to delete
+     * @returns Promise resolving when deleted
+     */
+    deleteRoom(roomId: string): Promise<void>;
+    /**
+     * Register a handler for when a new room is created
+     * @param handler - Called when a room is created
+     * @returns Unsubscribe function
+     */
+    onRoomCreated(handler: (room: RoomInfo) => void): () => void;
+    /**
+     * Register a handler for when a room is deleted
+     * @param handler - Called when a room is deleted
+     * @returns Unsubscribe function
+     */
+    onRoomDeleted(handler: (roomId: string) => void): () => void;
+    /**
+     * Register a connection handler
+     * @param handler - Called when connected
+     * @returns Unsubscribe function
+     */
+    onConnect(handler: () => void): () => void;
+    /**
+     * Register a disconnection handler
+     * @param handler - Called when disconnected with reason
+     * @returns Unsubscribe function
+     */
+    onDisconnect(handler: (reason: string) => void): () => void;
+    /**
+     * Register an error handler
+     * @param handler - Called on errors
+     * @returns Unsubscribe function
+     */
+    onError(handler: (error: Error) => void): () => void;
+    /**
+     * Register a handler for history events (sent when joining a room with syncHistoryOnJoin)
+     * @param handler - Called when history is received
+     * @returns Unsubscribe function
+     */
+    onHistory(handler: (roomId: string, events: EventMessage[]) => void): () => void;
+}
+/**
+ * Creates a Dialogue client for connecting to a Dialogue server from the frontend.
+ * Manages WebSocket connection, room membership, and event handling.
+ *
+ * @param config - Client configuration
+ * @returns DialogueClientInstance
+ *
+ * @example
+ * const client = createDialogueClient({
+ *   url: 'ws://localhost:3000',
+ *   auth: { userId: 'user-123', token: 'jwt-token' }
+ * })
+ *
+ * await client.connect()
+ *
+ * const chat = await client.join('chat')
+ * chat.on('message', (msg) => console.log(msg.data))
+ * chat.trigger('message', { text: 'Hello!' })
+ */
+declare function createDialogueClient(config: ClientConfig): DialogueClientInstance;
+
+/**
+ * Creates a room context for a joined room.
+ * Manages event subscriptions and triggers for a specific room.
+ *
+ * @param socket - Socket.IO client socket
+ * @param roomId - Room identifier
+ * @param roomName - Human-readable room name
+ * @param onLeave - Callback when leaving room
+ * @returns RoomContext with methods for interacting with the room
+ */
+declare function createRoomContext(socket: Socket, roomId: string, roomName: string, onLeave: () => void): RoomContext;
+
+export { type ClientConfig, type ConnectionResult, type ConnectionState, type CreateRoomOptions, type DialogueClientInstance, type DialogueError, type EventHandler, type EventMessage, type JoinResult, type RoomContext, type RoomInfo, type WildcardHandler, createDialogueClient, createRoomContext };

package/dist/client/index.d.ts

@@ -0,0 +1,273 @@
+import { Socket } from 'socket.io-client';
+
+/**
+ * Client-side type definitions for Dialogue
+ * These types mirror the backend types for consistent API
+ */
+/**
+ * Configuration for DialogueClient
+ */
+interface ClientConfig {
+    /** WebSocket server URL (e.g., 'ws://localhost:3000' or 'wss://example.com') */
+    url: string;
+    /** Authentication data sent with connection */
+    auth?: {
+        /** User ID for identification */
+        userId?: string;
+        /** JWT or other auth token */
+        token?: string;
+        /** Additional auth data */
+        [key: string]: unknown;
+    };
+    /** Auto-connect on instantiation (default: true) */
+    autoConnect?: boolean;
+    /** Reconnection options */
+    reconnection?: boolean;
+    /** Number of reconnection attempts */
+    reconnectionAttempts?: number;
+}
+/**
+ * Room info returned by listRooms
+ */
+interface RoomInfo {
+    id: string;
+    name: string;
+    description?: string;
+    size: number;
+    maxSize?: number;
+    createdById?: string;
+}
+/**
+ * Options for creating a room
+ */
+interface CreateRoomOptions {
+    /** Unique room identifier */
+    id: string;
+    /** Human-readable room name */
+    name: string;
+    /** Room description */
+    description?: string;
+    /** Maximum number of participants */
+    maxSize?: number;
+}
+/**
+ * Event message received from server
+ * Matches EventMessage from backend
+ */
+interface EventMessage<T = unknown> {
+    event: string;
+    roomId: string;
+    data: T;
+    from: string;
+    timestamp: number;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Error response from server
+ */
+interface DialogueError {
+    code: string;
+    message: string;
+}
+/**
+ * Connection result emitted on successful connect
+ */
+interface ConnectionResult {
+    clientId: string;
+    userId: string;
+}
+/**
+ * Room join result
+ */
+interface JoinResult {
+    roomId: string;
+    roomName: string;
+}
+/**
+ * Room context - represents a joined room with methods
+ */
+interface RoomContext {
+    /** Room ID */
+    readonly roomId: string;
+    /** Room name */
+    readonly roomName: string;
+    /**
+     * Trigger an event in this room
+     * @param eventName - Event name to trigger
+     * @param data - Event payload data
+     * @param meta - Optional metadata for flexible additional context
+     */
+    trigger<T>(eventName: string, data: T, meta?: Record<string, unknown>): void;
+    /**
+     * Listen for a specific event
+     * @param eventName - Event name to listen for
+     * @param handler - Callback when event received
+     * @returns Unsubscribe function
+     */
+    on<T>(eventName: string, handler: (msg: EventMessage<T>) => void): () => void;
+    /**
+     * Listen for all events in this room
+     * @param handler - Callback for any event
+     * @returns Unsubscribe function
+     */
+    onAny(handler: (eventName: string, msg: EventMessage<unknown>) => void): () => void;
+    /**
+     * Subscribe to additional event type
+     * @param eventName - Event name to subscribe to
+     */
+    subscribe(eventName: string): void;
+    /**
+     * Subscribe to all events in this room
+     * Tells the server to send all events from this room to this client
+     */
+    subscribeAll(): void;
+    /**
+     * Unsubscribe from event type
+     * @param eventName - Event name to unsubscribe from
+     */
+    unsubscribe(eventName: string): void;
+    /**
+     * Get historical events for this room (paginated, newest first)
+     * @param eventName - Event type to get history for
+     * @param start - Starting index (0 = most recent)
+     * @param end - Ending index (exclusive)
+     * @returns Promise resolving to array of events
+     */
+    getHistory<T = unknown>(eventName: string, start?: number, end?: number): Promise<EventMessage<T>[]>;
+    /**
+     * Leave this room
+     */
+    leave(): void;
+}
+/**
+ * Event handler type
+ */
+type EventHandler<T = unknown> = (msg: EventMessage<T>) => void;
+/**
+ * Wildcard event handler type
+ */
+type WildcardHandler = (eventName: string, msg: EventMessage<unknown>) => void;
+/**
+ * Connection state
+ */
+type ConnectionState = "disconnected" | "connecting" | "connected";
+
+/**
+ * Dialogue client instance returned by createDialogueClient
+ */
+interface DialogueClientInstance {
+    /** User ID assigned by the server */
+    readonly userId: string;
+    /** Whether the client is connected to the server */
+    readonly connected: boolean;
+    /** Current connection state */
+    readonly state: ConnectionState;
+    /**
+     * Connect to the server
+     * @returns Promise that resolves when connected
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the server
+     */
+    disconnect(): void;
+    /**
+     * Join a room
+     * @param roomId - Room ID to join
+     * @returns Promise resolving to RoomContext
+     */
+    join(roomId: string): Promise<RoomContext>;
+    /**
+     * Get a joined room context
+     * @param roomId - Room ID
+     * @returns RoomContext or undefined if not joined
+     */
+    getRoom(roomId: string): RoomContext | undefined;
+    /**
+     * List all available rooms on the server
+     * @returns Promise resolving to array of room info
+     */
+    listRooms(): Promise<RoomInfo[]>;
+    /**
+     * Create a new room on the server
+     * @param options - Room creation options
+     * @returns Promise resolving to created room info
+     */
+    createRoom(options: CreateRoomOptions): Promise<RoomInfo>;
+    /**
+     * Delete a room on the server (only creator can delete)
+     * @param roomId - Room ID to delete
+     * @returns Promise resolving when deleted
+     */
+    deleteRoom(roomId: string): Promise<void>;
+    /**
+     * Register a handler for when a new room is created
+     * @param handler - Called when a room is created
+     * @returns Unsubscribe function
+     */
+    onRoomCreated(handler: (room: RoomInfo) => void): () => void;
+    /**
+     * Register a handler for when a room is deleted
+     * @param handler - Called when a room is deleted
+     * @returns Unsubscribe function
+     */
+    onRoomDeleted(handler: (roomId: string) => void): () => void;
+    /**
+     * Register a connection handler
+     * @param handler - Called when connected
+     * @returns Unsubscribe function
+     */
+    onConnect(handler: () => void): () => void;
+    /**
+     * Register a disconnection handler
+     * @param handler - Called when disconnected with reason
+     * @returns Unsubscribe function
+     */
+    onDisconnect(handler: (reason: string) => void): () => void;
+    /**
+     * Register an error handler
+     * @param handler - Called on errors
+     * @returns Unsubscribe function
+     */
+    onError(handler: (error: Error) => void): () => void;
+    /**
+     * Register a handler for history events (sent when joining a room with syncHistoryOnJoin)
+     * @param handler - Called when history is received
+     * @returns Unsubscribe function
+     */
+    onHistory(handler: (roomId: string, events: EventMessage[]) => void): () => void;
+}
+/**
+ * Creates a Dialogue client for connecting to a Dialogue server from the frontend.
+ * Manages WebSocket connection, room membership, and event handling.
+ *
+ * @param config - Client configuration
+ * @returns DialogueClientInstance
+ *
+ * @example
+ * const client = createDialogueClient({
+ *   url: 'ws://localhost:3000',
+ *   auth: { userId: 'user-123', token: 'jwt-token' }
+ * })
+ *
+ * await client.connect()
+ *
+ * const chat = await client.join('chat')
+ * chat.on('message', (msg) => console.log(msg.data))
+ * chat.trigger('message', { text: 'Hello!' })
+ */
+declare function createDialogueClient(config: ClientConfig): DialogueClientInstance;
+
+/**
+ * Creates a room context for a joined room.
+ * Manages event subscriptions and triggers for a specific room.
+ *
+ * @param socket - Socket.IO client socket
+ * @param roomId - Room identifier
+ * @param roomName - Human-readable room name
+ * @param onLeave - Callback when leaving room
+ * @returns RoomContext with methods for interacting with the room
+ */
+declare function createRoomContext(socket: Socket, roomId: string, roomName: string, onLeave: () => void): RoomContext;
+
+export { type ClientConfig, type ConnectionResult, type ConnectionState, type CreateRoomOptions, type DialogueClientInstance, type DialogueError, type EventHandler, type EventMessage, type JoinResult, type RoomContext, type RoomInfo, type WildcardHandler, createDialogueClient, createRoomContext };