/**
 * @file aiagent_types.h
 * @brief AI Agent SDK 公开类型定义
 */

#ifndef AIAGENT_TYPES_H
#define AIAGENT_TYPES_H

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ========== 引擎状态 ========== */
typedef enum {
    AIAGENT_STATE_IDLE = 0,             /* 空闲 */
    AIAGENT_STATE_CONNECTING,           /* 连接中 */
    AIAGENT_STATE_READY,                /* 就绪 */
    AIAGENT_STATE_LISTENING,            /* 收音中 */
    AIAGENT_STATE_PROCESSING,           /* 云端处理中 */
    AIAGENT_STATE_SPEAKING,             /* 播放 TTS 中 */
    AIAGENT_STATE_INTERRUPTING,         /* 打断处理中 */
    AIAGENT_STATE_EXITING,              /* 退出中 */
} aiagent_state_t;

/* ========== 交互模式 ========== */
typedef enum {
    AIAGENT_INTERACT_PRESS = 0,         /* 按键说话 */
    AIAGENT_INTERACT_WAKEUP,            /* 唤醒词触发 */
    AIAGENT_INTERACT_CONTINUOUS,        /* 连续对话（语音打断） */
    AIAGENT_INTERACT_MAX
} aiagent_interact_mode_t;

/* ========== 错误码 ========== */
typedef enum {
    AIAGENT_OK = 0,
    AIAGENT_ERR_INVALID_PARAM = -1,
    AIAGENT_ERR_NOT_INIT = -2,
    AIAGENT_ERR_NETWORK = -3,
    AIAGENT_ERR_AUTH = -4,
    AIAGENT_ERR_BUSY = -5,
    AIAGENT_ERR_NO_MEMORY = -6,
    AIAGENT_ERR_NOT_CONNECTED = -7,
    AIAGENT_ERR_TIMEOUT = -8,
    AIAGENT_ERR_INTERNAL = -9,
} aiagent_error_t;

/* ========== 连接状态 ========== */
typedef enum {
    AIAGENT_CONN_DISCONNECTED = 0,
    AIAGENT_CONN_CONNECTING,
    AIAGENT_CONN_CONNECTED,
    AIAGENT_CONN_RECONNECTING,
} aiagent_conn_state_t;

/* ========== 事件类型（on_event 回调） ========== */
typedef enum {
    AIAGENT_EVT_VOICE_COMING = 0,       /* 云端检测到说话 */
    AIAGENT_EVT_VOICE_DISAPPEAR,        /* 用户停止说话 */
    AIAGENT_EVT_INTERRUPT,              /* 云端打断 */
    AIAGENT_EVT_CONID,                  /* 会话 ID 分配 */
    AIAGENT_EVT_AGENTID,                /* Agent ID 分配 */
    AIAGENT_EVT_LEAVING,                /* 云端断开 */
    AIAGENT_EVT_PLAY_AUDIO,             /* 云端请求播放音频 URL */
    AIAGENT_EVT_UPLOAD_IMAGE,           /* 云端请求上传图像 */
    AIAGENT_EVT_TAG_MSG,                /* 自定义 Tag 消息 */
    AIAGENT_EVT_MEDIA_GEN_RESULT,       /* 图像生成结果 */
    AIAGENT_EVT_REMOTE_PLAYER_BEGIN,    /* 云端音乐播放开始 */
    AIAGENT_EVT_REMOTE_PLAYER_END,      /* 云端音乐播放结束 */
    AIAGENT_EVT_DIRECT_PLAY,            /* 直连 URL 音乐播放 */
    AIAGENT_EVT_GENERIC,                /* 未单独分类的 [E]:... 事件，原文透传 */
} aiagent_event_type_t;

/* ========== ASR 扩展信息（情绪/声纹） ==========
 *
 * 仅在 AIAGENT_ASR_TEXT_EXT=1 且云端开启 asr_text_ext 时填充，
 * 协议格式：[Q]:text|||[session_id]:x&[finish]:y&[emotion]:z&[nick_name]:n
 *
 * 生命周期：仅在回调期间有效，需保留请自行拷贝。
 */
typedef struct {
    const char *emotion;    /* 情绪标签（逗号分隔，按置信度降序），无则 NULL */
    const char *name;       /* 声纹昵称，无则 NULL */
    const char *session_id; /* 本轮 ASR session_id，无则 NULL */
    bool        finish;     /* 是否最终识别帧 */
} aiagent_asr_ext_t;

/* ========== 事件回调 ========== */
typedef struct {
    /* 状态变化 */
    void (*on_state_change)(aiagent_state_t old_state, aiagent_state_t new_state, void *user_ctx);
    /* ASR 识别文本 */
    void (*on_asr_result)(const char *text, bool is_final, void *user_ctx);

    /* ASR 识别文本（含情绪/声纹扩展，ext 为 NULL 表示无扩展） */
    void (*on_asr_result_ext)(const char *text, bool is_final,
                              const aiagent_asr_ext_t *ext, void *user_ctx);

    /* AI 回复文本（流式） */
    void (*on_ai_response)(const char *text, bool is_final, void *user_ctx);
    /* 下行 PCM 音频 */
    void (*on_audio_data)(const uint8_t *data, size_t len, void *user_ctx);

    /* Function Call 回调：返回 1=已处理，0=fallback 到内置 FC 注册表 */
    int  (*on_function_call)(const char *session_id, const char *name,
                             const char *params, void *user_ctx);

    /* 错误通知 */
    void (*on_error)(aiagent_error_t code, const char *msg, void *user_ctx);
    /* TTS 开始/结束 */
    void (*on_tts_event)(bool is_start, void *user_ctx);
    /* 鉴权结果 */
    void (*on_license_result)(bool pass, void *user_ctx);
    /* 通用事件 */
    void (*on_event)(aiagent_event_type_t event, const char *data, size_t data_len, void *user_ctx);
    void *user_ctx;
} aiagent_callbacks_t;

#ifdef __cplusplus
}
#endif

#endif /* AIAGENT_TYPES_H */
