/**
 * zulip-js类型声明文件
 * 
 * 功能描述：
 * - 为zulip-js库提供TypeScript类型定义
 * - 支持IDE代码提示和类型检查
 * 
 * 职责分离：
 * - 类型声明层：为第三方库提供TypeScript类型支持
 * - 接口定义层：定义库的API接口结构
 * - 类型安全层：确保编译时的类型检查
 * 
 * 最近修改：
 * - 2026-01-12: 代码规范优化 - 修正注释规范和修改记录格式 (修改者: moyin)
 * - 2026-01-08: 文件夹扁平化 - 从types/子文件夹移动到上级目录 (修改者: moyin)
 * - 2026-01-07: 代码规范优化 - 文件重命名和注释规范 (修改者: moyin)
 * 
 * @author moyin
 * @version 1.0.3
 * @since 2025-12-25
 * @lastModified 2026-01-12
 */

declare module 'zulip-js' {
  /**
   * Zulip配置接口
   */
  interface ZulipConfig {
    username?: string;
    apiKey?: string;
    password?: string;
    realm?: string;
    zuliprc?: string;
  }

  /**
   * Zulip API响应基础接口
   */
  interface ZulipResponse {
    result: 'success' | 'error';
    msg?: string;
  }

  /**
   * 用户信息接口
   */
  interface UserProfile extends ZulipResponse {
    email?: string;
    user_id?: number;
    full_name?: string;
    is_admin?: boolean;
    is_bot?: boolean;
  }

  /**
   * 消息发送响应接口
   */
  interface SendMessageResponse extends ZulipResponse {
    id?: number;
  }

  /**
   * 队列注册响应接口
   */
  interface RegisterQueueResponse extends ZulipResponse {
    queue_id?: string;
    last_event_id?: number;
  }

  /**
   * 事件接口
   */
  interface ZulipEvent {
    id: number;
    type: string;
    message?: {
      id: number;
      sender_email: string;
      sender_full_name: string;
      content: string;
      stream_id: number;
      subject: string;
      timestamp: number;
    };
  }

  /**
   * 获取事件响应接口
   */
  interface GetEventsResponse extends ZulipResponse {
    events?: ZulipEvent[];
  }

  /**
   * 消息发送参数接口
   */
  interface SendMessageParams {
    type: 'stream' | 'private';
    to: string | string[];
    subject?: string;
    content: string;
  }

  /**
   * 队列注册参数接口
   */
  interface RegisterQueueParams {
    event_types?: string[];
    narrow?: Array<[string, string]>;
    all_public_streams?: boolean;
  }

  /**
   * 获取事件参数接口
   */
  interface GetEventsParams {
    queue_id: string;
    last_event_id: number;
    dont_block?: boolean;
  }

  /**
   * 注销队列参数接口
   */
  interface DeregisterQueueParams {
    queue_id: string;
  }

  /**
   * Zulip客户端接口
   */
  interface ZulipClient {
    users: {
      me: {
        getProfile(): Promise<UserProfile>;
        pointer: {
          retrieve(): Promise<ZulipResponse & { pointer?: number }>;
          update(params: { pointer: number }): Promise<ZulipResponse>;
        };
        subscriptions(): Promise<ZulipResponse>;
      };
      retrieve(): Promise<ZulipResponse & { members?: any[] }>;
      create(params: any): Promise<ZulipResponse>;
    };
    messages: {
      send(params: SendMessageParams): Promise<SendMessageResponse>;
      retrieve(params: any): Promise<ZulipResponse & { messages?: any[] }>;
      render(params: { content: string }): Promise<ZulipResponse & { rendered?: string }>;
      update(params: any): Promise<ZulipResponse>;
      flags: {
        add(params: { flag: string; messages: number[] }): Promise<ZulipResponse>;
        remove(params: { flag: string; messages: number[] }): Promise<ZulipResponse>;
      };
      getById(params: { message_id: number }): Promise<ZulipResponse & { message?: any }>;
      getHistoryById(params: { message_id: number }): Promise<ZulipResponse>;
      deleteReactionById(params: { message_id: number; emoji_name?: string }): Promise<ZulipResponse>;
      deleteById(params: { message_id: number }): Promise<ZulipResponse>;
    };
    queues: {
      register(params?: RegisterQueueParams): Promise<RegisterQueueResponse>;
      deregister(params: DeregisterQueueParams): Promise<ZulipResponse>;
    };
    events: {
      retrieve(params: GetEventsParams): Promise<GetEventsResponse>;
    };
    streams: {
      retrieve(): Promise<ZulipResponse & { streams?: any[] }>;
      getStreamId(params: { stream: string }): Promise<ZulipResponse & { stream_id?: number }>;
      subscriptions: {
        retrieve(): Promise<ZulipResponse & { subscriptions?: any[] }>;
      };
      deleteById(params: { stream_id: number }): Promise<ZulipResponse>;
      topics: {
        retrieve(params: { stream_id: number }): Promise<ZulipResponse & { topics?: any[] }>;
      };
    };
    typing: {
      send(params: { to: string | string[]; op: 'start' | 'stop' }): Promise<ZulipResponse>;
    };
    reactions: {
      add(params: { message_id: number; emoji_name: string; emoji_code?: string; reaction_type?: string }): Promise<ZulipResponse>;
      remove(params: { message_id: number; emoji_code: string; reaction_type?: string }): Promise<ZulipResponse>;
    };
    emojis: {
      retrieve(): Promise<ZulipResponse & { emoji?: any }>;
    };
    filters: {
      retrieve(): Promise<ZulipResponse & { filters?: any[] }>;
    };
    server: {
      settings(): Promise<ZulipResponse & { [key: string]: any }>;
    };
    accounts: {
      retrieve(): Promise<ZulipResponse & { api_key?: string }>;
    };
    callEndpoint(endpoint: string, method: string, params?: any): Promise<ZulipResponse>;
  }

  /**
   * Zulip初始化函数
   */
  function zulipInit(config: ZulipConfig): Promise<ZulipClient>;

  export = zulipInit;
}