/**
 * API 相关类型定义
 * @module types/api
 */

/**
 * 通用响应结果
 * 所有 API 接口的标准响应格式
 * 
 * @template T 响应数据的类型
 * 
 * @example
 * ```typescript
 * const result: Result<string> = {
 *   code: 0,
 *   msg: 'success',
 *   data: 'Hello World'
 * }
 * ```
 */
export interface Result<T = any> {
  /** 
   * 状态码
   * - `0`: 成功
   * - 其他值: 失败
   */
  code: number;
  
  /** 
   * 响应消息
   * 描述请求的结果或错误信息
   */
  msg: string;
  
  /** 
   * 响应数据
   * 具体的业务数据
   */
  data: T;
}

/**
 * 消息角色
 * 用于标识对话中的发言者
 */
export type MessageRole = 
  /** 用户 */
  | 'user' 
  /** AI 助手 */
  | 'assistant' 
  /** 系统 */
  | 'system';

/**
 * 对话消息
 * 表示对话中的一条消息
 * 
 * @example
 * ```typescript
 * const message: Message = {
 *   role: 'user',
 *   content: '你好，请介绍一下自己'
 * }
 * ```
 */
export interface Message {
  /** 
   * 消息角色
   * 标识这条消息的发言者
   */
  role: MessageRole;
  
  /** 
   * 消息内容
   * 具体的文本内容
   */
  content: string;
}

/**
 * TTS 音色
 * 文本转语音时使用的声音类型
 */
export type TTSRole = 
  /** 女声 */
  | 'woman' 
  /** 男声 */
  | 'man' 
  /** 晓晓（女声） */
  | 'xiaoxiao' 
  /** 云霄（男声） */
  | 'yunxiao' 
  /** 云皓（男声） */
  | 'yunhao';

/**
 * TTS 模型
 * 文本转语音使用的模型类型
 */
export type TTSModel = 
  /** GPT-SoVITS 模型 */
  | 'gpt-sovits' 
  /** 讯飞模型 */
  | 'xunfei' 
  /** PaddleSpeech 模型 */
  | 'paddle' 
  /** PaddleSpeech v2 模型 */
  | 'paddle2' 
  /** Azure 模型 */
  | 'azure';

/**
 * TTS 口型类型
 * BlendShapes 数据的格式类型
 */
export type TTSViseme = 
  /** Azure 格式 */
  | 'azure' 
  /** Oculus OVR 格式 */
  | 'ovr' 
  /** Audio2Face 格式 */
  | 'a2f' 
  /** 全特格式 */
  | 'qt' 
  /** 无口型数据 */
  | 'none' 
  /** Audio2Face 3D 格式 */
  | 'a2f3d';

/**
 * 对话响应模式
 */
export type ChatResponseMode = 
  /** 流式响应，实时返回结果 */
  | 'streaming' 
  /** 阻塞式响应，等待完整结果 */
  | 'blocking';

/**
 * 对话文件
 * 用于在对话中上传图片等文件
 * 
 * @example
 * ```typescript
 * const file: ChatFile = {
 *   type: 'image',
 *   transfer_method: 'remote_url',
 *   url: 'https://example.com/image.jpg'
 * }
 * ```
 */
export interface ChatFile {
  /** 
   * 文件类型
   * 目前仅支持图片
   */
  type: 'image';
  
  /** 
   * 传输方式
   * - `remote_url`: 远程网络地址
   * - `local_file`: 本地文件
   */
  transfer_method: 'remote_url' | 'local_file';
  
  /** 
   * 文件地址
   * 图片的 URL 或本地路径
   */
  url: string;
}

/**
 * 对话参数
 * 用于 askStream 方法的参数配置
 * 
 * @example
 * ```typescript
 * // 单轮对话
 * const params: AskParams = {
 *   message: [
 *     { role: 'user', content: '你好' }
 *   ]
 * }
 * 
 * // 多轮对话（带上下文）
 * const params: AskParams = {
 *   message: [
 *     { role: 'user', content: '今天天气怎么样？' },
 *     { role: 'assistant', content: '今天天气晴朗。' },
 *     { role: 'user', content: '那适合户外运动吗？' }
 *   ],
 *   conversation_id: 'conv-123'
 * }
 * 
 * // 带图片的对话
 * const params: AskParams = {
 *   message: [
 *     { role: 'user', content: '这是什么？' }
 *   ],
 *   files: [
 *     {
 *       type: 'image',
 *       transfer_method: 'remote_url',
 *       url: 'https://example.com/image.jpg'
 *     }
 *   ]
 * }
 * ```
 */
export interface AskParams {
  /** 
   * 请求 ID
   * 可选的唯一标识符，用于追踪请求
   * @example 'req-123456'
   */
  reqId?: string;
  
  /** 
   * 消息列表
   * 对话的消息历史，包含用户和助手的消息
   * 支持多轮对话，按时间顺序排列
   */
  message: Message[];
  
  /** 
   * 会话 ID
   * 用于标识同一个对话会话，保持上下文连贯性
   * @example 'conv-123456'
   */
  conversation_id?: string;
  
  /** 
   * 响应模式
   * - `streaming`: 流式响应（默认），实时返回结果
   * - `blocking`: 阻塞式响应，等待完整结果
   * @default 'streaming'
   */
  response_mode?: ChatResponseMode;
  
  /** 
   * 文件列表
   * 可选的文件附件，如图片
   */
  files?: ChatFile[];
  
  /** 
   * 命令类型
   * 用于特殊命令处理
   * @internal
   */
  commandType?: string;
  
  /** 
   * 输入参数
   * 额外的输入参数
   * @internal
   */
  inputs?: Record<string, any>;
}

/**
 * 对话消息参数（用于旧版 API）
 * @deprecated 请使用 AskParams
 */
export interface ChatMessageParams extends Omit<AskParams, 'reqId'> {
  /** 语言 */
  language?: string;
  /** 查询文本（从 message 中提取） */
  query?: string;
}

/**
 * 对话消息事件
 */
export interface ChatMessage {
  /** 事件类型 */
  event: 'message' | 'message_end' | 'error';
  /** 会话 ID */
  conversation_id: string;
  /** 消息 ID */
  message_id: string;
  /** 创建时间 */
  created_at: number;
  /** 任务 ID */
  task_id: string;
  /** ID */
  id: string;
  /** 回答内容 */
  answer: string;
  /** 来源变量选择器 */
  from_variable_selector?: string;
  /** 消息内容 */
  message?: string;
}

/**
 * 播放信息
 */
export interface PlayInfo {
  /** BlendShapes 数据 */
  shapes: number[][];
  /** 音频链接 */
  url: string;
  /** 音频时长（秒） */
  duration: number;
  /** 文本内容 */
  content: string;
}

/**
 * 流式音频播放信息
 */
export interface StreamAudioPlayInfo {
  /** BlendShapes 数据 */
  shapes: number[][];
  /** 音频数据 */
  audios: ArrayBuffer[];
  /** 音频时长（秒） */
  duration: number;
  /** 文本内容 */
  content: string;
  /** 音频采样率 */
  rate: number;
}

/**
 * 对话错误信息
 */
export interface AskError {
  /** 文本内容 */
  content: string;
  /** 错误消息 */
  errorMessage: string;
}

/**
 * 对话响应
 */
export interface AskResponse {
  /** 请求 ID */
  reqId: string;
  /** 播放信息列表 */
  playInfos: PlayInfo[];
  /** 错误信息列表 */
  errorInfos: AskError[];
}

/**
 * 流式对话响应
 */
export interface AskStreamResponse {
  /** 请求 ID */
  reqId: string;
  /** 播放信息列表 */
  playInfos: StreamAudioPlayInfo[];
  /** 错误信息列表 */
  errorInfos: AskError[];
}

/**
 * TTS 参数
 */
export interface TTSParams {
  /** 音色 */
  role?: TTSRole;
  /** 内容 */
  content: string;
  /** 语速，默认: 1 */
  speed?: number;
  /** 模型，默认: gpt-sovits */
  model?: TTSModel;
  /** 口型，默认: a2f */
  viseme?: TTSViseme;
  /** 是否开启平滑 [0: 关闭，1: 开启]，默认开启 */
  smooth_method?: number;
  /** 平滑值：[1~10]，默认5 */
  smooth_iterations?: number;
}

/**
 * TTS 响应
 */
export interface TTSResponse {
  /** 音频 URL */
  url: string;
  /** 音频时长（秒） */
  duration: number;
  /** BlendShapes 数据 */
  blend_shapes: number[] | number[][];
  /** 语音文本 */
  content: string;
}

/**
 * 语音识别结果
 */
export interface Voice2TextResult {
  /** 是否为最终结果 */
  is_final: boolean;
  /** 识别文本 */
  text: string;
  /** 音频文件名 */
  wav_name?: string;
  /** 模型 */
  mode?: string;
  /** 置信度 */
  confidence?: number;
}

/**
 * 数字人信息
 */
export interface CharacterInfo {
  id: string;
  name: string;
  description: string;
  language: string;
  token: string;
  timbre?: any;
  animations?: any[];
  aposes?: any[];
  scene?: any;
  configuration?: any;
  pronunciations?: any[];
  renderings?: string[];
  animationEnabled?: string;
}

/**
 * 数字人模型文件
 */
export interface CharacterModel {
  id: string;
  name: string;
  enabled: boolean;
  code: string;
  bundle: string;
  type: 'apose' | 'animation' | 'animation_system';
}

/**
 * 录音权限结果
 */
export interface RecorderPermission {
  /** 状态码 */
  code?: string;
  /** 消息 */
  msg?: string;
  /** 用户是否拒绝权限 */
  isUserNotAllow?: boolean;
}

/**
 * 对话回调函数
 */
export type AskCallback = (result: Result<ChatMessage>) => void;

/**
 * 播报回调函数
 */
export type SpeakCallback = (result: Result<TTSResponse>) => void;

/**
 * 语音识别回调函数
 */
export type Voice2TextCallback = (result: Voice2TextResult) => void;
