@roomkit/client 1.0.0

package/README.md

@@ -0,0 +1,300 @@
+# @roomkit/client
+
+Client SDK for Gateway-Worker Framework - A TypeScript SDK inspired by Colyseus.
+
+## Features
+
+- 🎯 **Colyseus-inspired API** - Familiar and intuitive for game developers
+- 🔐 **Type-safe** - Full TypeScript support with generics
+- 🔌 **WebSocket-based** - Real-time bidirectional communication
+- 🔄 **Auto-reconnection** - Configurable reconnection strategy
+- ❤️ **Heartbeat** - Automatic connection health monitoring
+- 🎮 **Room abstraction** - Easy room management and state synchronization
+- 📦 **Lightweight** - Minimal dependencies
+
+## Installation
+
+```bash
+pnpm add @roomkit/client
+```
+
+## Quick Start
+
+### 1. Create a Client
+
+```typescript
+import { Client } from '@roomkit/client';
+
+const client = new Client('ws://localhost:27100/ws', {
+  autoReconnect: true,
+  reconnectDelay: 1000,
+  maxReconnectAttempts: 10,
+});
+```
+
+### 2. Authenticate
+
+```typescript
+await client.auth('your-auth-token');
+console.log('Authenticated as:', client.userId);
+```
+
+### 3. Join or Create a Room
+
+```typescript
+interface GameState {
+  players: { [id: string]: PlayerData };
+  gameStatus: 'waiting' | 'playing' | 'finished';
+}
+
+const room = await client.joinOrCreate<GameState>('my-game', {
+  maxPlayers: 4,
+});
+
+console.log('Joined room:', room.id);
+```
+
+### 4. Listen to State Changes
+
+```typescript
+room.onStateChange((state) => {
+  console.log('State updated:', state);
+  // Update your UI based on new state
+});
+```
+
+### 5. Listen to Messages
+
+```typescript
+// Listen to specific message types
+room.onMessage('player_joined', (message) => {
+  console.log('New player:', message);
+});
+
+// Listen to game events
+room.onMessage('game_started', (message) => {
+  console.log('Game started!');
+});
+```
+
+### 6. Send Messages
+
+```typescript
+// Send game actions
+room.send('player_action', {
+  type: 'move',
+  x: 100,
+  y: 200,
+});
+
+// Request with response
+const result = await room.request('make_move', {
+  position: 5,
+});
+console.log('Move result:', result);
+```
+
+### 7. Leave Room
+
+```typescript
+await room.leave();
+```
+
+## API Reference
+
+### Client
+
+#### Constructor
+
+```typescript
+new Client(url: string, options?: ClientOptions)
+```
+
+**Options:**
+- `autoReconnect?: boolean` - Auto-reconnect on disconnect (default: `true`)
+- `reconnectDelay?: number` - Delay between reconnection attempts in ms (default: `1000`)
+- `maxReconnectAttempts?: number` - Maximum reconnection attempts (default: `10`)
+- `requestTimeout?: number` - Request timeout in ms (default: `10000`)
+- `heartbeatInterval?: number` - Heartbeat interval in ms (default: `20000`)
+
+#### Methods
+
+##### `async auth(token: string): Promise<void>`
+Authenticate with the server.
+
+##### `async create<State>(roomName: string, options?: RoomOptions): Promise<Room<State>>`
+Create a new room.
+
+##### `async join<State>(roomId: string, options?: RoomOptions): Promise<Room<State>>`
+Join an existing room.
+
+##### `async joinOrCreate<State>(roomName: string, options?: RoomOptions): Promise<Room<State>>`
+Join an existing room or create a new one (recommended).
+
+##### `async getAvailableRooms(roomName?: string): Promise<AvailableRoom[]>`
+Get list of available rooms.
+
+##### `disconnect(): void`
+Disconnect from the server.
+
+#### Properties
+
+- `state: ConnectionState` - Current connection state
+- `userId: string | null` - Current user ID (after auth)
+- `isConnected: boolean` - Whether client is connected
+- `isAuthenticated: boolean` - Whether client is authenticated
+
+### Room
+
+#### Properties
+
+- `id: string` - Room ID
+- `sessionId: string` - Session ID
+- `name: string` - Room name
+- `state: State | null` - Current room state
+
+#### Methods
+
+##### `onStateChange(callback: (state: State) => void): () => void`
+Listen to state changes. Returns an unsubscribe function.
+
+##### `onJoin(callback: () => void): () => void`
+Listen to room join event.
+
+##### `onLeave(callback: (code: number) => void): () => void`
+Listen to room leave event.
+
+##### `onError(callback: (code: number, message: string) => void): () => void`
+Listen to error events.
+
+##### `onMessage<T>(type: number | string, callback: (message: T) => void): () => void`
+Listen to custom messages.
+
+##### `send(type: number | string, message?: any): void`
+Send a message to the room.
+
+##### `async request<T>(type: number | string, message?: any): Promise<T>`
+Send a request and wait for response.
+
+##### `async leave(consented?: boolean): Promise<void>`
+Leave the room.
+
+## Examples
+
+### Basic Game Client
+
+```typescript
+import { Client } from '@roomkit/client';
+
+class GameClient {
+  private client: Client;
+  private room: Room | null = null;
+
+  constructor() {
+    this.client = new Client('ws://localhost:27100/ws');
+  }
+
+  async connect(token: string) {
+    await this.client.auth(token);
+  }
+
+  async joinGame(gameType: string) {
+    this.room = await this.client.joinOrCreate(gameType);
+    
+    this.room.onStateChange((state) => {
+      this.onStateUpdate(state);
+    });
+    
+    this.room.onMessage('game_event', (event) => {
+      this.onGameEvent(event);
+    });
+    
+    this.room.onLeave(() => {
+      console.log('Left room');
+      this.room = null;
+    });
+  }
+
+  async sendAction(action: any) {
+    if (this.room) {
+      this.room.send('player_action', action);
+    }
+  }
+
+  private onStateUpdate(state: any) {
+    // Update UI
+  }
+
+  private onGameEvent(event: any) {
+    // Handle game events
+  }
+}
+```
+
+### Blackjack Client Example
+
+See [examples/blackjack-client.ts](./examples/blackjack-client.ts) for a complete example.
+
+## Type Safety
+
+The SDK provides full TypeScript support:
+
+```typescript
+interface MyGameState {
+  round: number;
+  players: {
+    id: string;
+    score: number;
+    ready: boolean;
+  }[];
+}
+
+const room = await client.joinOrCreate<MyGameState>('my-game');
+
+// state is typed as MyGameState
+room.onStateChange((state) => {
+  console.log(state.round); // TypeScript knows this exists
+  console.log(state.players); // Fully typed
+});
+```
+
+## Advanced Usage
+
+### Custom Message IDs
+
+```typescript
+import { MessageId } from '@roomkit/client';
+
+// Use predefined message IDs
+room.send(MessageId.PLAYER_READY, { ready: true });
+
+// Or use custom string types (auto-hashed)
+room.send('my_custom_action', { data: 'value' });
+```
+
+### Connection State Monitoring
+
+```typescript
+client.onStateChange((state) => {
+  console.log('Connection state:', state);
+  // 'disconnected' | 'connecting' | 'connected' | 'authenticated'
+});
+```
+
+### Error Handling
+
+```typescript
+room.onError((code, message) => {
+  console.error(`Room error ${code}:`, message);
+});
+
+try {
+  await room.leave();
+} catch (error) {
+  console.error('Failed to leave room:', error);
+}
+```
+
+## License
+
+MIT

package/dist/Client.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Client - 主客户端类
+ * 类似 Colyseus 的 Client API
+ */
+import { Room, RoomOptions } from './Room.js';
+export interface ClientOptions {
+    /** Auto-reconnect on disconnect */
+    autoReconnect?: boolean;
+    /** Reconnect delay in milliseconds */
+    reconnectDelay?: number;
+    /** Maximum reconnect attempts */
+    maxReconnectAttempts?: number;
+    /** Request timeout in milliseconds */
+    requestTimeout?: number;
+    /** Heartbeat interval in milliseconds */
+    heartbeatInterval?: number;
+}
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'authenticated';
+/**
+ * Client 类 - Gateway-Worker 框架的客户端
+ *
+ * @example
+ * ```typescript
+ * import { Client } from '@roomkit/client';
+ *
+ * const client = new Client('ws://localhost:27100/ws');
+ *
+ * // 连接并认证
+ * await client.auth('my-token');
+ *
+ * // 加入或创建房间
+ * const room = await client.joinOrCreate<MyGameState>('poker', {
+ *   maxPlayers: 6
+ * });
+ *
+ * // 监听状态变化
+ * room.onStateChange((state) => {
+ *   console.log('State:', state);
+ * });
+ *
+ * // 发送消息
+ * room.send('player_action', { action: 'fold' });
+ * ```
+ */
+export declare class Client {
+    private url;
+    private ws;
+    private options;
+    private pendingRequests;
+    private reqCounter;
+    private reconnectAttempts;
+    private heartbeatTimer;
+    private sessionToken;
+    private _state;
+    private _userId;
+    private _rooms;
+    private stateListeners;
+    constructor(url: string, options?: ClientOptions);
+    get state(): ConnectionState;
+    get userId(): string | null;
+    get isConnected(): boolean;
+    get isAuthenticated(): boolean;
+    /**
+     * 连接到服务器
+     */
+    connect(): Promise<void>;
+    /**
+     * 认证（连接 + 认证一步完成）
+     */
+    auth(token: string): Promise<void>;
+    /**
+     * 断开连接
+     */
+    disconnect(): void;
+    /**
+     * 生成唯一的房间ID
+     */
+    private generateRoomId;
+    /**
+     * 创建房间
+     *
+     * 注意：Room 对象会先注册再发送请求，确保能接收到 STATE_FULL 消息
+     */
+    create<State = any>(roomName: string, options?: RoomOptions): Promise<Room<State>>;
+    /**
+     * 加入房间
+     *
+     * 注意：Room 对象会先注册再发送请求，确保能接收到 STATE_FULL 消息
+     */
+    join<State = any>(roomId: string, options?: RoomOptions): Promise<Room<State>>;
+    /**
+     * 加入或创建房间（推荐使用）
+     *
+     * 注意：Room 对象会先注册再发送请求，确保能接收到 STATE_FULL 消息
+     */
+    joinOrCreate<State = any>(roomName: string, options?: RoomOptions): Promise<Room<State>>;
+    /**
+     * 根据条件加入房间
+     */
+    joinBy<State = any>(roomName: string, criteria?: Record<string, unknown>): Promise<Room<State>>;
+    /**
+     * 获取房间列表（需要后端支持）
+     */
+    getAvailableRooms(roomName?: string): Promise<any[]>;
+    /**
+     * 重新连接到房间（断线重连）
+     */
+    reconnect<State = any>(roomId: string, sessionId: string): Promise<Room<State>>;
+    /**
+     * 自动重连（使用 sessionToken）
+     *
+     * 在 WebSocket 断开后自动调用
+     */
+    private autoReconnect;
+    /**
+     * 移除房间引用（内部使用）
+     */
+    removeRoom(roomId: string): void;
+    /**
+     * 获取当前所有房间
+     */
+    getRooms(): Room[];
+    /**
+     * 发送消息（不等待响应）
+     * @param msgIdOrType 消息ID（数字）或消息类型（字符串）
+     * @param payload 消息内容
+     * @param roomId 目标房间ID（多房间模式必须指定）
+     */
+    send(msgIdOrType: number | string, payload?: unknown, roomId?: string): void;
+    /**
+     * 发送请求并等待响应
+     * @param msgIdOrType 消息ID（数字）或消息类型（字符串）
+     * @param payload 消息内容
+     * @param roomId 目标房间ID（多房间模式必须指定）
+     */
+    request<T>(msgIdOrType: number | string, payload?: unknown, roomId?: string): Promise<T>;
+    /**
+     * 监听连接状态变化
+     */
+    onStateChange(listener: (state: ConnectionState) => void): () => void;
+    private setState;
+    private handleMessage;
+    /**
+     * 检查是否为响应消息
+     */
+    private isResponseMessage;
+    private routeToRoom;
+    private handleDisconnect;
+    private cleanupPendingRequests;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private logger;
+}
+//# sourceMappingURL=Client.d.ts.map

package/dist/Client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Client.d.ts","sourceRoot":"","sources":["../src/Client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AA6C9C,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,sCAAsC;IACtC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iCAAiC;IACjC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,sCAAsC;IACtC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,YAAY,GACZ,WAAW,GACX,eAAe,CAAC;AAUpB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,MAAM;IAoBf,OAAO,CAAC,GAAG;IAnBb,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,eAAe,CAIlB;IACL,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,YAAY,CAAuB;IAE3C,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,MAAM,CAA2B;IAEzC,OAAO,CAAC,cAAc,CAAoD;gBAGhE,GAAG,EAAE,MAAM,EACnB,OAAO,GAAE,aAAkB;IAO7B,IAAI,KAAK,IAAI,eAAe,CAE3B;IAED,IAAI,MAAM,IAAI,MAAM,GAAG,IAAI,CAE1B;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,eAAe,IAAI,OAAO,CAE7B;IAID;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAyC9B;;OAEG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBxC;;OAEG;IACH,UAAU,IAAI,IAAI;IAoBlB;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;;;OAIG;IACG,MAAM,CAAC,KAAK,GAAG,GAAG,EACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAmDvB;;;;OAIG;IACG,IAAI,CAAC,KAAK,GAAG,GAAG,EACpB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IA0CvB;;;;OAIG;IACG,YAAY,CAAC,KAAK,GAAG,GAAG,EAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAmDvB;;OAEG;IACG,MAAM,CAAC,KAAK,GAAG,GAAG,EACtB,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACrC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAKvB;;OAEG;IACG,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAQ1D;;OAEG;IACG,SAAS,CAAC,KAAK,GAAG,GAAG,EACzB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAMvB;;;;OAIG;YACW,aAAa;IAsC3B;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQhC;;OAEG;IACH,QAAQ,IAAI,IAAI,EAAE;IAMlB;;;;;OAKG;IACH,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,GAAE,OAAY,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAYhF;;;;;OAKG;IACH,OAAO,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,GAAE,OAAY,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAwC5F;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI;IAOrE,OAAO,CAAC,QAAQ;IAWhB,OAAO,CAAC,aAAa;IAyDrB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,WAAW;IAyCnB,OAAO,CAAC,gBAAgB;IAmCxB,OAAO,CAAC,sBAAsB;IAQ9B,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,MAAM;CAKf"}