go-chat-sdk 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,500 @@
+//#region types.d.ts
+declare enum ChatType {
+  Single = "single",
+  Group = "group"
+}
+declare enum MessageType {
+  Text = "text",
+  Image = "image",
+  Video = "video",
+  File = "file"
+}
+interface Message {
+  /** 服务器生成的消息ID */
+  msg_id: string;
+  /** 客户端生成的消息ID(用于去重) */
+  client_msg_id: string;
+  /** 发送者ID */
+  sender_id: string;
+  /** 接收者ID(用户ID或群ID) */
+  receiver_id: string;
+  /** 聊天类型: single(单聊) / group(群聊) */
+  chat_type: ChatType;
+  /** 服务器时间戳(微秒级) */
+  server_time: number;
+  /** 回复的消息ID(可选) */
+  reply_to_msg_id?: string;
+  /** 消息类型: text/image/video/file */
+  msg_type: MessageType;
+  /** 消息内容负载 */
+  payload: unknown;
+  /** 扩展字段 */
+  ext?: Record<string, unknown>;
+  /** 创建时间 */
+  created_at?: string;
+}
+interface SendMessageRequest {
+  /** 客户端生成的唯一消息ID */
+  client_msg_id?: string;
+  /** 接收者ID */
+  receiver_id: string;
+  /** 聊天类型 */
+  chat_type: ChatType;
+  /** 消息类型 */
+  msg_type: MessageType;
+  /** 消息内容负载 */
+  payload: unknown;
+  /** 回复的消息ID(可选) */
+  reply_to_msg_id?: string;
+  /** 扩展字段(可选) */
+  ext?: Record<string, unknown>;
+}
+interface TextPayload {
+  text: string;
+}
+interface ImagePayload {
+  url: string;
+  width?: number;
+  height?: number;
+  size?: number;
+}
+interface VideoPayload {
+  url: string;
+  duration?: number;
+  width?: number;
+  height?: number;
+  size?: number;
+  thumbnail_url?: string;
+}
+interface FilePayload {
+  url: string;
+  name: string;
+  size: number;
+  mime_type?: string;
+}
+interface RegisterRequest {
+  username: string;
+  password: string;
+}
+interface LoginRequest {
+  username: string;
+  password: string;
+}
+interface UserResponse {
+  user_id: string;
+  username: string;
+  token: string;
+}
+interface BatchGenerateRequest {
+  count: number;
+}
+interface BatchUserResponse {
+  user_id: string;
+  username: string;
+  password: string;
+  token: string;
+}
+interface ChatSDKOptions {
+  /** API基础URL */
+  baseURL: string;
+  /** WebSocket网关URL */
+  gatewayURL: string;
+  /** 自动重连间隔(毫秒),默认3000ms */
+  reconnectInterval?: number;
+  /** 最大重连次数,默认10次 */
+  maxReconnectAttempts?: number;
+  /** 心跳间隔(毫秒),默认30000ms */
+  heartbeatInterval?: number;
+  /** 消息缓冲区大小,默认100 */
+  messageBufferSize?: number;
+}
+declare enum ConnectionState {
+  Disconnected = "disconnected",
+  Connecting = "connecting",
+  Connected = "connected",
+  Reconnecting = "reconnecting",
+  Error = "error"
+}
+declare enum ChatEventType {
+  MessageReceived = "message:received",
+  MessageSent = "message:sent",
+  ConnectionStateChange = "connection:state:change",
+  Error = "error",
+  Connect = "connect",
+  Disconnect = "disconnect"
+}
+interface MessageReceivedData {
+  message: Message;
+}
+interface MessageSentData {
+  client_msg_id: string;
+  server_msg_id?: string;
+  server_time?: number;
+}
+interface ConnectionStateChangeData {
+  state: ConnectionState;
+  previousState: ConnectionState;
+}
+interface ErrorData {
+  code: string;
+  message: string;
+  originalError?: Error;
+}
+interface ConnectData {
+  timestamp: number;
+}
+interface DisconnectData {
+  code?: number;
+  reason?: string;
+}
+interface ChatEventDataMap {
+  [ChatEventType.MessageReceived]: MessageReceivedData;
+  [ChatEventType.MessageSent]: MessageSentData;
+  [ChatEventType.ConnectionStateChange]: ConnectionStateChangeData;
+  [ChatEventType.Error]: ErrorData;
+  [ChatEventType.Connect]: ConnectData;
+  [ChatEventType.Disconnect]: DisconnectData;
+}
+type ChatEvent<T extends ChatEventType = ChatEventType> = {
+  type: T;
+  data: T extends keyof ChatEventDataMap ? ChatEventDataMap[T] : unknown;
+  timestamp: number;
+};
+type EventListener<T extends ChatEventType = ChatEventType> = (event: ChatEvent<T>) => void;
+interface HistoryQueryParams {
+  /** 接收者ID */
+  receiver_id: string;
+  /** 聊天类型 */
+  chat_type: ChatType;
+  /** 查询此时间戳之前的消息(微秒级,默认为当前时间) */
+  before_server_time?: number;
+  /** 每页数量(默认20) */
+  page_size?: number;
+}
+interface HistoryMessagesResponse {
+  messages: Message[];
+  hasMore: boolean;
+}
+//#endregion
+//#region utils.d.ts
+/**
+ * 事件发射器 - 用于SDK内部事件管理
+ */
+declare class EventEmitter {
+  private listeners;
+  /**
+   * 监听事件
+   */
+  on<T extends ChatEventType>(event: T, listener: EventListener<T>): () => void;
+  /**
+   * 监听一次性事件
+   */
+  once<T extends ChatEventType>(event: T, listener: EventListener<T>): void;
+  /**
+   * 取消监听
+   */
+  off<T extends ChatEventType>(event: T, listener: EventListener<T>): void;
+  /**
+   * 触发事件
+   */
+  emit<T extends ChatEventType>(event: T, data: ChatEvent<T>['data']): void;
+  /**
+   * 移除所有监听器
+   */
+  removeAllListeners(event?: ChatEventType): void;
+}
+/**
+ * 生成UUID v4
+ */
+declare function generateUUID(): string;
+/**
+ * 检查字符串是否为有效的UUID
+ */
+declare function isValidUUID(str: string): boolean;
+/**
+ * 延迟函数
+ */
+declare function delay(ms: number): Promise<void>;
+/**
+ * 创建错误数据对象
+ */
+declare function createError(code: string, message: string, originalError?: Error): ErrorData;
+/**
+ * 创建连接状态变更数据
+ */
+declare function createStateChange(state: ConnectionState, previousState: ConnectionState): ConnectionStateChangeData;
+//#endregion
+//#region api.d.ts
+/**
+ * API 客户端 - 处理所有 HTTP 请求
+ */
+declare class APIClient {
+  private baseURL;
+  private token;
+  constructor(baseURL: string);
+  /**
+   * 设置认证 Token
+   */
+  setToken(token: string): void;
+  /**
+   * 清除认证 Token
+   */
+  clearToken(): void;
+  /**
+   * 获取当前 Token
+   */
+  getToken(): string | null;
+  /**
+   * 构建请求头
+   */
+  private getHeaders;
+  /**
+   * 发送 HTTP 请求
+   */
+  private request;
+  /**
+   * 用户注册
+   */
+  register(req: RegisterRequest): Promise<UserResponse>;
+  /**
+   * 用户登录
+   */
+  login(req: LoginRequest): Promise<UserResponse>;
+  /**
+   * 批量生成用户
+   */
+  batchGenerate(req: BatchGenerateRequest): Promise<{
+    users: BatchUserResponse[];
+  }>;
+  /**
+   * 获取历史消息
+   * 注意:后端目前只提供了按 conversation 查询的接口
+   */
+  getHistoryMessages(params: HistoryQueryParams): Promise<HistoryMessagesResponse>;
+}
+/**
+ * API 错误类
+ */
+declare class APIError extends Error {
+  statusCode: number;
+  data: Record<string, unknown>;
+  constructor(statusCode: number, message: string, data?: Record<string, unknown>);
+}
+//#endregion
+//#region websocket.d.ts
+/**
+ * WebSocket 连接管理器
+ */
+declare class WebSocketManager {
+  private ws;
+  private options;
+  private emitter;
+  private currentState;
+  private reconnectAttempts;
+  private reconnectTimer;
+  private heartbeatTimer;
+  private messageQueue;
+  private token;
+  private intentionalClose;
+  constructor(options: ChatSDKOptions, emitter: EventEmitter);
+  /**
+   * 设置认证 Token
+   */
+  setToken(token: string): void;
+  /**
+   * 清除认证 Token
+   */
+  clearToken(): void;
+  /**
+   * 获取当前连接状态
+   */
+  getState(): ConnectionState;
+  /**
+   * 是否已连接
+   */
+  isConnected(): boolean;
+  /**
+   * 更新连接状态并触发事件
+   */
+  private setState;
+  /**
+   * 连接到 WebSocket 网关
+   */
+  connect(): Promise<void>;
+  /**
+   * 断开 WebSocket 连接
+   */
+  disconnect(): void;
+  /**
+   * 发送消息
+   */
+  sendMessage(req: SendMessageRequest): void;
+  /**
+   * 构建发送的消息对象
+   */
+  private buildMessage;
+  /**
+   * 设置 WebSocket 事件处理器
+   */
+  private setupWebSocketHandlers;
+  /**
+   * 处理接收到的消息
+   */
+  private handleMessage;
+  /**
+   * 启动心跳
+   */
+  private startHeartbeat;
+  /**
+   * 安排重连
+   */
+  private scheduleReconnect;
+  /**
+   * 清空定时器
+   */
+  private clearTimers;
+  /**
+   * 刷新消息队列(连接成功后发送缓存的消息)
+   */
+  private flushMessageQueue;
+}
+//#endregion
+//#region index.d.ts
+/**
+ * ChatSDK - 类型安全的聊天 SDK
+ *
+ * 使用示例:
+ * ```typescript
+ * const sdk = new ChatSDK({
+ *   baseURL: 'http://localhost:8080',
+ *   gatewayURL: 'ws://localhost:8081/ws',
+ * });
+ *
+ * // 注册/登录
+ * await sdk.register({ username: 'test', password: '123456' });
+ * await sdk.login({ username: 'test', password: '123456' });
+ *
+ * // 连接 WebSocket
+ * await sdk.connect();
+ *
+ * // 监听消息
+ * sdk.on(ChatEventType.MessageReceived, (event) => {
+ *   console.log('收到消息:', event.data.message);
+ * });
+ *
+ * // 发送文本消息
+ * sdk.sendTextMessage({
+ *   receiver_id: 'xxx',
+ *   chat_type: ChatType.Single,
+ *   text: 'Hello!',
+ * });
+ * ```
+ */
+declare class ChatSDK {
+  private api;
+  private wsManager;
+  private emitter;
+  private options;
+  private currentUser;
+  constructor(options: ChatSDKOptions);
+  /**
+   * 监听事件 - 类型安全的事件监听
+   */
+  on<T extends ChatEventType>(event: T, listener: EventListener<T>): () => void;
+  /**
+   * 监听一次性事件 - 类型安全的事件监听
+   */
+  once<T extends ChatEventType>(event: T, listener: EventListener<T>): void;
+  /**
+   * 取消监听
+   */
+  off<T extends ChatEventType>(event: T, listener: EventListener<T>): void;
+  /**
+   * 移除所有监听器
+   */
+  removeAllListeners(event?: ChatEventType): void;
+  /**
+   * 用户注册
+   */
+  register(req: RegisterRequest): Promise<UserResponse>;
+  /**
+   * 用户登录
+   */
+  login(req: LoginRequest): Promise<UserResponse>;
+  /**
+   * 批量生成用户(测试/管理用途)
+   */
+  batchGenerateUsers(req: BatchGenerateRequest): Promise<BatchUserResponse[]>;
+  /**
+   * 设置认证信息
+   */
+  setAuth(user: UserResponse): void;
+  /**
+   * 清除认证信息
+   */
+  clearAuth(): void;
+  /**
+   * 获取当前用户信息
+   */
+  getCurrentUser(): UserResponse | null;
+  /**
+   * 检查是否已认证
+   */
+  isAuthenticated(): boolean;
+  /**
+   * 连接到消息网关
+   */
+  connect(): Promise<void>;
+  /**
+   * 断开消息网关连接
+   */
+  disconnect(): void;
+  /**
+   * 获取连接状态
+   */
+  getConnectionState(): ConnectionState;
+  /**
+   * 是否已连接
+   */
+  isConnected(): boolean;
+  /**
+   * 发送原始消息
+   */
+  sendMessage(req: SendMessageRequest): void;
+  /**
+   * 发送文本消息
+   */
+  sendTextMessage(params: Omit<SendMessageRequest, 'client_msg_id' | 'msg_type' | 'payload'> & {
+    text: string;
+  }): void;
+  /**
+   * 发送图片消息
+   */
+  sendImageMessage(params: Omit<SendMessageRequest, 'client_msg_id' | 'msg_type' | 'payload'> & ImagePayload): void;
+  /**
+   * 发送视频消息
+   */
+  sendVideoMessage(params: Omit<SendMessageRequest, 'client_msg_id' | 'msg_type' | 'payload'> & VideoPayload): void;
+  /**
+   * 发送文件消息
+   */
+  sendFileMessage(params: Omit<SendMessageRequest, 'client_msg_id' | 'msg_type' | 'payload'> & FilePayload): void;
+  /**
+   * 获取历史消息
+   */
+  getHistoryMessages(params: HistoryQueryParams): Promise<HistoryMessagesResponse>;
+  /**
+   * 生成 UUID(用于 client_msg_id)
+   */
+  generateMessageId(): string;
+  /**
+   * 验证 UUID 格式
+   */
+  validateMessageId(id: string): boolean;
+  /**
+   * 设置事件转发
+   */
+  private setupEventForwarding;
+}
+//#endregion
+export { APIClient, APIError, BatchGenerateRequest, BatchUserResponse, ChatEvent, ChatEventDataMap, ChatEventType, ChatSDK, ChatSDK as default, ChatSDKOptions, ChatType, ConnectData, ConnectionState, ConnectionStateChangeData, DisconnectData, ErrorData, EventEmitter, EventListener, FilePayload, HistoryMessagesResponse, HistoryQueryParams, ImagePayload, LoginRequest, Message, MessageReceivedData, MessageSentData, MessageType, RegisterRequest, SendMessageRequest, TextPayload, UserResponse, VideoPayload, WebSocketManager, createError, createStateChange, delay, generateUUID, isValidUUID };

package/dist/index.mjs

@@ -0,0 +1,696 @@
+//#region types.ts
+let ChatType = /* @__PURE__ */ function(ChatType) {
+	ChatType["Single"] = "single";
+	ChatType["Group"] = "group";
+	return ChatType;
+}({});
+let MessageType = /* @__PURE__ */ function(MessageType) {
+	MessageType["Text"] = "text";
+	MessageType["Image"] = "image";
+	MessageType["Video"] = "video";
+	MessageType["File"] = "file";
+	return MessageType;
+}({});
+let ConnectionState = /* @__PURE__ */ function(ConnectionState) {
+	ConnectionState["Disconnected"] = "disconnected";
+	ConnectionState["Connecting"] = "connecting";
+	ConnectionState["Connected"] = "connected";
+	ConnectionState["Reconnecting"] = "reconnecting";
+	ConnectionState["Error"] = "error";
+	return ConnectionState;
+}({});
+let ChatEventType = /* @__PURE__ */ function(ChatEventType) {
+	ChatEventType["MessageReceived"] = "message:received";
+	ChatEventType["MessageSent"] = "message:sent";
+	ChatEventType["ConnectionStateChange"] = "connection:state:change";
+	ChatEventType["Error"] = "error";
+	ChatEventType["Connect"] = "connect";
+	ChatEventType["Disconnect"] = "disconnect";
+	return ChatEventType;
+}({});
+//#endregion
+//#region api.ts
+/**
+* API 客户端 - 处理所有 HTTP 请求
+*/
+var APIClient = class {
+	constructor(baseURL) {
+		this.token = null;
+		this.baseURL = baseURL.replace(/\/$/, "");
+	}
+	/**
+	* 设置认证 Token
+	*/
+	setToken(token) {
+		this.token = token;
+	}
+	/**
+	* 清除认证 Token
+	*/
+	clearToken() {
+		this.token = null;
+	}
+	/**
+	* 获取当前 Token
+	*/
+	getToken() {
+		return this.token;
+	}
+	/**
+	* 构建请求头
+	*/
+	getHeaders() {
+		const headers = { "Content-Type": "application/json" };
+		if (this.token) headers["Authorization"] = `Bearer ${this.token}`;
+		return headers;
+	}
+	/**
+	* 发送 HTTP 请求
+	*/
+	async request(method, endpoint, body) {
+		const url = `${this.baseURL}${endpoint}`;
+		const options = {
+			method,
+			headers: this.getHeaders()
+		};
+		if (body !== void 0) options.body = JSON.stringify(body);
+		const response = await fetch(url, options);
+		if (!response.ok) {
+			const errorData = await response.json().catch(() => ({}));
+			throw new APIError(response.status, errorData.error || `HTTP ${response.status}: ${response.statusText}`, errorData);
+		}
+		if (response.status === 204) return;
+		return response.json();
+	}
+	/**
+	* 用户注册
+	*/
+	async register(req) {
+		return this.request("POST", "/api/v1/users/register", req);
+	}
+	/**
+	* 用户登录
+	*/
+	async login(req) {
+		const resp = await this.request("POST", "/api/v1/users/login", req);
+		this.setToken(resp.token);
+		return resp;
+	}
+	/**
+	* 批量生成用户
+	*/
+	async batchGenerate(req) {
+		return this.request("POST", "/api/v1/users/batch", req);
+	}
+	/**
+	* 获取历史消息
+	* 注意:后端目前只提供了按 conversation 查询的接口
+	*/
+	async getHistoryMessages(params) {
+		const queryParams = new URLSearchParams();
+		queryParams.append("receiver_id", params.receiver_id);
+		queryParams.append("chat_type", params.chat_type);
+		if (params.before_server_time !== void 0) queryParams.append("before_server_time", params.before_server_time.toString());
+		if (params.page_size !== void 0) queryParams.append("page_size", params.page_size.toString());
+		const messages = await this.request("GET", `/api/v1/messages/history?${queryParams.toString()}`);
+		return {
+			messages: messages || [],
+			hasMore: messages.length === (params.page_size || 20)
+		};
+	}
+};
+/**
+* API 错误类
+*/
+var APIError = class extends Error {
+	constructor(statusCode, message, data = {}) {
+		super(message);
+		this.name = "APIError";
+		this.statusCode = statusCode;
+		this.data = data;
+	}
+};
+//#endregion
+//#region utils.ts
+/**
+* 事件发射器 - 用于SDK内部事件管理
+*/
+var EventEmitter = class {
+	constructor() {
+		this.listeners = /* @__PURE__ */ new Map();
+	}
+	/**
+	* 监听事件
+	*/
+	on(event, listener) {
+		if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
+		this.listeners.get(event).add(listener);
+		return () => {
+			this.off(event, listener);
+		};
+	}
+	/**
+	* 监听一次性事件
+	*/
+	once(event, listener) {
+		const onceWrapper = (e) => {
+			this.off(event, onceWrapper);
+			listener(e);
+		};
+		this.on(event, onceWrapper);
+	}
+	/**
+	* 取消监听
+	*/
+	off(event, listener) {
+		const set = this.listeners.get(event);
+		if (set) {
+			set.delete(listener);
+			if (set.size === 0) this.listeners.delete(event);
+		}
+	}
+	/**
+	* 触发事件
+	*/
+	emit(event, data) {
+		const set = this.listeners.get(event);
+		if (set) {
+			const eventObj = {
+				type: event,
+				data,
+				timestamp: Date.now()
+			};
+			set.forEach((listener) => {
+				try {
+					listener(eventObj);
+				} catch (err) {
+					console.error(`Event listener error for ${event}:`, err);
+				}
+			});
+		}
+	}
+	/**
+	* 移除所有监听器
+	*/
+	removeAllListeners(event) {
+		if (event) this.listeners.delete(event);
+		else this.listeners.clear();
+	}
+};
+/**
+* 生成UUID v4
+*/
+function generateUUID() {
+	return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+		const r = Math.random() * 16 | 0;
+		return (c === "x" ? r : r & 3 | 8).toString(16);
+	});
+}
+/**
+* 检查字符串是否为有效的UUID
+*/
+function isValidUUID(str) {
+	return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(str);
+}
+/**
+* 延迟函数
+*/
+function delay(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* 创建错误数据对象
+*/
+function createError(code, message, originalError) {
+	return {
+		code,
+		message,
+		originalError
+	};
+}
+/**
+* 创建连接状态变更数据
+*/
+function createStateChange(state, previousState) {
+	return {
+		state,
+		previousState
+	};
+}
+//#endregion
+//#region websocket.ts
+/**
+* WebSocket 连接管理器
+*/
+var WebSocketManager = class {
+	constructor(options, emitter) {
+		this.ws = null;
+		this.currentState = "disconnected";
+		this.reconnectAttempts = 0;
+		this.reconnectTimer = null;
+		this.heartbeatTimer = null;
+		this.messageQueue = [];
+		this.token = null;
+		this.intentionalClose = false;
+		this.options = {
+			baseURL: options.baseURL,
+			gatewayURL: options.gatewayURL,
+			reconnectInterval: options.reconnectInterval ?? 3e3,
+			maxReconnectAttempts: options.maxReconnectAttempts ?? 10,
+			heartbeatInterval: options.heartbeatInterval ?? 3e4,
+			messageBufferSize: options.messageBufferSize ?? 100
+		};
+		this.emitter = emitter;
+	}
+	/**
+	* 设置认证 Token
+	*/
+	setToken(token) {
+		this.token = token;
+	}
+	/**
+	* 清除认证 Token
+	*/
+	clearToken() {
+		this.token = null;
+	}
+	/**
+	* 获取当前连接状态
+	*/
+	getState() {
+		return this.currentState;
+	}
+	/**
+	* 是否已连接
+	*/
+	isConnected() {
+		return this.currentState === "connected" && this.ws?.readyState === WebSocket.OPEN;
+	}
+	/**
+	* 更新连接状态并触发事件
+	*/
+	setState(newState) {
+		const previousState = this.currentState;
+		this.currentState = newState;
+		this.emitter.emit("connection:state:change", createStateChange(newState, previousState));
+	}
+	/**
+	* 连接到 WebSocket 网关
+	*/
+	async connect() {
+		if (this.isConnected()) return;
+		if (!this.token) throw new Error("Token is required before connecting to WebSocket");
+		this.intentionalClose = false;
+		this.setState("connecting");
+		try {
+			const wsUrl = new URL(this.options.gatewayURL);
+			wsUrl.searchParams.append("token", this.token);
+			this.ws = new WebSocket(wsUrl.toString());
+			await this.setupWebSocketHandlers();
+		} catch (error) {
+			this.setState("error");
+			this.emitter.emit("error", createError("WS_CONNECT_FAILED", "Failed to connect to WebSocket", error instanceof Error ? error : void 0));
+			this.scheduleReconnect();
+			throw error;
+		}
+	}
+	/**
+	* 断开 WebSocket 连接
+	*/
+	disconnect() {
+		this.intentionalClose = true;
+		this.clearTimers();
+		if (this.ws) {
+			if (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) this.ws.close(1e3, "Client disconnect");
+			this.ws = null;
+		}
+		this.reconnectAttempts = 0;
+		this.setState("disconnected");
+		this.emitter.emit("disconnect", void 0);
+	}
+	/**
+	* 发送消息
+	*/
+	sendMessage(req) {
+		if (!this.isConnected()) {
+			this.messageQueue.push(req);
+			this.emitter.emit("error", createError("WS_NOT_CONNECTED", "WebSocket not connected, message queued"));
+			return;
+		}
+		const message = this.buildMessage(req);
+		this.ws.send(JSON.stringify(message));
+	}
+	/**
+	* 构建发送的消息对象
+	*/
+	buildMessage(req) {
+		return {
+			client_msg_id: req.client_msg_id,
+			receiver_id: req.receiver_id,
+			chat_type: req.chat_type,
+			msg_type: req.msg_type,
+			payload: req.payload,
+			...req.reply_to_msg_id && { reply_to_msg_id: req.reply_to_msg_id },
+			...req.ext && { ext: req.ext }
+		};
+	}
+	/**
+	* 设置 WebSocket 事件处理器
+	*/
+	setupWebSocketHandlers() {
+		return new Promise((resolve, reject) => {
+			if (!this.ws) {
+				reject(/* @__PURE__ */ new Error("WebSocket instance is null"));
+				return;
+			}
+			this.ws.onopen = () => {
+				this.reconnectAttempts = 0;
+				this.setState("connected");
+				this.emitter.emit("connect", void 0);
+				this.startHeartbeat();
+				this.flushMessageQueue();
+				resolve();
+			};
+			this.ws.onmessage = (event) => {
+				this.handleMessage(event.data);
+			};
+			this.ws.onclose = (event) => {
+				this.clearTimers();
+				if (this.intentionalClose) {
+					this.setState("disconnected");
+					this.emitter.emit("disconnect", {
+						code: event.code,
+						reason: event.reason
+					});
+				} else {
+					this.setState("reconnecting");
+					this.scheduleReconnect();
+				}
+			};
+			this.ws.onerror = (error) => {
+				this.emitter.emit("error", createError("WS_ERROR", "WebSocket error occurred", error instanceof Error ? error : void 0));
+				reject(error);
+			};
+		});
+	}
+	/**
+	* 处理接收到的消息
+	*/
+	handleMessage(data) {
+		try {
+			const message = JSON.parse(data);
+			if (!message.msg_id || !message.sender_id) {
+				this.emitter.emit("error", createError("INVALID_MESSAGE", "Received invalid message format"));
+				return;
+			}
+			this.emitter.emit("message:received", { message });
+		} catch (error) {
+			this.emitter.emit("error", createError("MESSAGE_PARSE_ERROR", data, error instanceof Error ? error : void 0));
+		}
+	}
+	/**
+	* 启动心跳
+	*/
+	startHeartbeat() {
+		this.heartbeatTimer = setInterval(() => {
+			if (this.isConnected()) this.ws.send(JSON.stringify({ type: "ping" }));
+		}, this.options.heartbeatInterval);
+	}
+	/**
+	* 安排重连
+	*/
+	scheduleReconnect() {
+		if (this.reconnectAttempts >= this.options.maxReconnectAttempts) {
+			this.setState("error");
+			this.emitter.emit("error", createError("MAX_RECONNECT_REACHED", "Maximum reconnection attempts reached"));
+			return;
+		}
+		this.reconnectAttempts++;
+		this.reconnectTimer = setTimeout(() => {
+			this.connect().catch(() => {});
+		}, this.options.reconnectInterval * this.reconnectAttempts);
+	}
+	/**
+	* 清空定时器
+	*/
+	clearTimers() {
+		if (this.reconnectTimer) {
+			clearTimeout(this.reconnectTimer);
+			this.reconnectTimer = null;
+		}
+		if (this.heartbeatTimer) {
+			clearInterval(this.heartbeatTimer);
+			this.heartbeatTimer = null;
+		}
+	}
+	/**
+	* 刷新消息队列(连接成功后发送缓存的消息)
+	*/
+	flushMessageQueue() {
+		while (this.messageQueue.length > 0) {
+			const req = this.messageQueue.shift();
+			if (req) this.sendMessage(req);
+		}
+	}
+};
+//#endregion
+//#region index.ts
+/**
+* ChatSDK - 类型安全的聊天 SDK
+*
+* 使用示例:
+* ```typescript
+* const sdk = new ChatSDK({
+*   baseURL: 'http://localhost:8080',
+*   gatewayURL: 'ws://localhost:8081/ws',
+* });
+*
+* // 注册/登录
+* await sdk.register({ username: 'test', password: '123456' });
+* await sdk.login({ username: 'test', password: '123456' });
+*
+* // 连接 WebSocket
+* await sdk.connect();
+*
+* // 监听消息
+* sdk.on(ChatEventType.MessageReceived, (event) => {
+*   console.log('收到消息:', event.data.message);
+* });
+*
+* // 发送文本消息
+* sdk.sendTextMessage({
+*   receiver_id: 'xxx',
+*   chat_type: ChatType.Single,
+*   text: 'Hello!',
+* });
+* ```
+*/
+var ChatSDK = class {
+	constructor(options) {
+		this.currentUser = null;
+		this.options = {
+			baseURL: options.baseURL,
+			gatewayURL: options.gatewayURL,
+			reconnectInterval: options.reconnectInterval ?? 3e3,
+			maxReconnectAttempts: options.maxReconnectAttempts ?? 10,
+			heartbeatInterval: options.heartbeatInterval ?? 3e4,
+			messageBufferSize: options.messageBufferSize ?? 100
+		};
+		this.emitter = new EventEmitter();
+		this.api = new APIClient(this.options.baseURL);
+		this.wsManager = new WebSocketManager(this.options, this.emitter);
+		this.setupEventForwarding();
+	}
+	/**
+	* 监听事件 - 类型安全的事件监听
+	*/
+	on(event, listener) {
+		return this.emitter.on(event, listener);
+	}
+	/**
+	* 监听一次性事件 - 类型安全的事件监听
+	*/
+	once(event, listener) {
+		this.emitter.once(event, listener);
+	}
+	/**
+	* 取消监听
+	*/
+	off(event, listener) {
+		this.emitter.off(event, listener);
+	}
+	/**
+	* 移除所有监听器
+	*/
+	removeAllListeners(event) {
+		this.emitter.removeAllListeners(event);
+	}
+	/**
+	* 用户注册
+	*/
+	async register(req) {
+		const resp = await this.api.register(req);
+		this.setAuth(resp);
+		return resp;
+	}
+	/**
+	* 用户登录
+	*/
+	async login(req) {
+		const resp = await this.api.login(req);
+		this.setAuth(resp);
+		return resp;
+	}
+	/**
+	* 批量生成用户(测试/管理用途)
+	*/
+	async batchGenerateUsers(req) {
+		return (await this.api.batchGenerate(req)).users;
+	}
+	/**
+	* 设置认证信息
+	*/
+	setAuth(user) {
+		this.currentUser = user;
+		this.api.setToken(user.token);
+		this.wsManager.setToken(user.token);
+	}
+	/**
+	* 清除认证信息
+	*/
+	clearAuth() {
+		this.currentUser = null;
+		this.api.clearToken();
+		this.wsManager.clearToken();
+	}
+	/**
+	* 获取当前用户信息
+	*/
+	getCurrentUser() {
+		return this.currentUser;
+	}
+	/**
+	* 检查是否已认证
+	*/
+	isAuthenticated() {
+		return !!this.currentUser && !!this.api.getToken();
+	}
+	/**
+	* 连接到消息网关
+	*/
+	async connect() {
+		if (!this.isAuthenticated()) throw new Error("Must be authenticated before connecting");
+		return this.wsManager.connect();
+	}
+	/**
+	* 断开消息网关连接
+	*/
+	disconnect() {
+		this.wsManager.disconnect();
+	}
+	/**
+	* 获取连接状态
+	*/
+	getConnectionState() {
+		return this.wsManager.getState();
+	}
+	/**
+	* 是否已连接
+	*/
+	isConnected() {
+		return this.wsManager.isConnected();
+	}
+	/**
+	* 发送原始消息
+	*/
+	sendMessage(req) {
+		if (!req.client_msg_id) req.client_msg_id = generateUUID();
+		this.wsManager.sendMessage(req);
+		this.emitter.emit("message:sent", { client_msg_id: req.client_msg_id });
+	}
+	/**
+	* 发送文本消息
+	*/
+	sendTextMessage(params) {
+		const { text, ...rest } = params;
+		this.sendMessage({
+			...rest,
+			msg_type: "text",
+			payload: { text }
+		});
+	}
+	/**
+	* 发送图片消息
+	*/
+	sendImageMessage(params) {
+		const { url, width, height, size, ...rest } = params;
+		this.sendMessage({
+			...rest,
+			msg_type: "image",
+			payload: {
+				url,
+				width,
+				height,
+				size
+			}
+		});
+	}
+	/**
+	* 发送视频消息
+	*/
+	sendVideoMessage(params) {
+		const { url, duration, width, height, size, thumbnail_url, ...rest } = params;
+		this.sendMessage({
+			...rest,
+			msg_type: "video",
+			payload: {
+				url,
+				duration,
+				width,
+				height,
+				size,
+				thumbnail_url
+			}
+		});
+	}
+	/**
+	* 发送文件消息
+	*/
+	sendFileMessage(params) {
+		const { url, name, size, mime_type, ...rest } = params;
+		this.sendMessage({
+			...rest,
+			msg_type: "file",
+			payload: {
+				url,
+				name,
+				size,
+				mime_type
+			}
+		});
+	}
+	/**
+	* 获取历史消息
+	*/
+	async getHistoryMessages(params) {
+		return this.api.getHistoryMessages(params);
+	}
+	/**
+	* 生成 UUID(用于 client_msg_id)
+	*/
+	generateMessageId() {
+		return generateUUID();
+	}
+	/**
+	* 验证 UUID 格式
+	*/
+	validateMessageId(id) {
+		return isValidUUID(id);
+	}
+	/**
+	* 设置事件转发
+	*/
+	setupEventForwarding() {}
+};
+//#endregion
+export { APIClient, APIError, ChatEventType, ChatSDK, ChatSDK as default, ChatType, ConnectionState, EventEmitter, MessageType, WebSocketManager, createError, createStateChange, delay, generateUUID, isValidUUID };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "go-chat-sdk",
+  "version": "1.0.0",
+  "description": "Type-safe Chat SDK for Go-Chat IM service",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "chat",
+    "sdk",
+    "websocket",
+    "im",
+    "instant-messaging",
+    "typescript"
+  ],
+  "author": "sanbei101",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@types/ws": "^8.18.1",
+    "tsdown": "^0.21.9",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5",
+    "ws": "^8.20.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}