snowluma/api_ext.go

package snowluma

import "context"

// 本文件收录 SnowLuma 独有、napcat 未覆盖的扩展动作。
// 返回结构未结构化的动作统一返回 jsonRaw（map），需要更细结构时用 Call 裸调自行解码。
// 未收录的动作一律可通过 Client.Call / Context.Call 裸调。

// ---- 闪传（flash transfer） ----

// CreateFlashTask 创建闪传任务，返回 fileset 信息。
func (a API) CreateFlashTask(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "create_flash_task", params)
}

// GetFilesetInfo 获取文件集信息。
func (a API) GetFilesetInfo(ctx context.Context, filesetID string) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_fileset_info", H{"fileset_id": filesetID})
}

// GetFlashFileList 获取闪传文件集内的文件列表。
func (a API) GetFlashFileList(ctx context.Context, filesetID string) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_flash_file_list", H{"fileset_id": filesetID})
}

// ListFilesets 列出当前账号的所有闪传文件集。
func (a API) ListFilesets(ctx context.Context) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "list_filesets", H{})
}

// GetFlashFileURL 获取闪传文件链接。
func (a API) GetFlashFileURL(ctx context.Context, filesetID, fileID string) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_flash_file_url", H{"fileset_id": filesetID, "file_id": fileID})
}

// GetShareLink 获取文件分享链接。
func (a API) GetShareLink(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_share_link", params)
}

// DeleteFlashFile 删除闪传文件。
func (a API) DeleteFlashFile(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "delete_flash_file", params)
	return err
}

// RenameFlashFile 重命名闪传文件。
func (a API) RenameFlashFile(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "rename_flash_file", params)
	return err
}

// DownloadFileset 解析闪传文件下载直链（不下载，由调用方实现下载）。
func (a API) DownloadFileset(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "download_fileset", params)
}

// SendFlashMsg 发送闪传消息（私聊或群聊，引用 fileset_id 让对端下载）。
func (a API) SendFlashMsg(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "send_flash_msg", params)
}

// GetFilesetID 从 QQ 闪传分享码或官方分享链接获取 fileset_id。
func (a API) GetFilesetID(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_fileset_id", params)
}

// ---- Ark 卡片 ----

// SendGroupArkShare 分享群 Ark 卡片（NapCat 标准名）。
func (a API) SendGroupArkShare(ctx context.Context, groupID int64, ark string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "send_group_ark_share", H{"group_id": groupID, "ark": ark})
	return err
}

// SendArkShare 分享用户/群 Ark 卡片（NapCat 标准名）。
func (a API) SendArkShare(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "send_ark_share", params)
	return err
}

// SharePeer 分享用户/群推荐 Ark 卡片。
func (a API) SharePeer(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "share_peer", params)
}

// ShareGroupEx 分享群 Ark 卡片。
func (a API) ShareGroupEx(ctx context.Context, groupID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "share_group_ex", H{"group_id": groupID})
}

// SendTuwenArk 发送图文 Ark 卡片（私聊/群聊）。
func (a API) SendTuwenArk(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "send_tuwen_ark", params)
	return err
}

// ClickInlineKeyboardButton 点击内联键盘按钮。
func (a API) ClickInlineKeyboardButton(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "click_inline_keyboard_button", params)
	return err
}

// ---- 群待办 ----

// GetGroupTodoList 获取群待办列表。
func (a API) GetGroupTodoList(ctx context.Context, groupID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_group_todo_list", H{"group_id": groupID})
}

// SetGroupTodo 设置群待办。
func (a API) SetGroupTodo(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_todo", params)
	return err
}

// CompleteGroupTodo 完成群待办。
func (a API) CompleteGroupTodo(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "complete_group_todo", params)
	return err
}

// CancelGroupTodo 取消群待办。
func (a API) CancelGroupTodo(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "cancel_group_todo", params)
	return err
}

// ---- 群分类标签 / 群管理扩展 ----

// GetGroupTags 读取某个群分类下的资料标签。
func (a API) GetGroupTags(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_group_tags", params)
}

// AddGroupTag 向某个群分类添加资料标签。
func (a API) AddGroupTag(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "add_group_tag", params)
	return err
}

// DeleteGroupTag 从某个群分类移除资料标签。
func (a API) DeleteGroupTag(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "delete_group_tag", params)
	return err
}

// GetGroupAdminSettings 获取群管理设置的当前值。
func (a API) GetGroupAdminSettings(ctx context.Context, groupID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_group_admin_settings", H{"group_id": groupID})
}

// SetGroupKickMembers 批量踢出群成员。
func (a API) SetGroupKickMembers(ctx context.Context, groupID int64, userIDs []int64, rejectAddRequest bool) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_kick_members", H{"group_id": groupID, "user_ids": userIDs, "reject_add_request": rejectAddRequest})
	return err
}

// SetGroupAddOption 设置加群选项。
func (a API) SetGroupAddOption(ctx context.Context, groupID int64, option string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_add_option", H{"group_id": groupID, "option": option})
	return err
}

// SetGroupSearch 设置群被搜索方式（群指纹 / 群号搜索开关）。
func (a API) SetGroupSearch(ctx context.Context, groupID int64, searchable bool) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_search", H{"group_id": groupID, "searchable": searchable})
	return err
}

// SetGroupMemberInvitePolicy 设置群成员邀请策略。
func (a API) SetGroupMemberInvitePolicy(ctx context.Context, groupID int64, policy string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_member_invite_policy", H{"group_id": groupID, "policy": policy})
	return err
}

// SetGroupNewMemberHistoryVisibility 设置新成员是否可查看历史消息。
func (a API) SetGroupNewMemberHistoryVisibility(ctx context.Context, groupID int64, visible bool) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_new_member_history_visibility", H{"group_id": groupID, "visible": visible})
	return err
}

// SetGroupMemberPermissions 设置群成员权限（仅群主可改）。
func (a API) SetGroupMemberPermissions(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_member_permissions", params)
	return err
}

// SetGroupRobotAddOption 设置群机器人加群选项。
func (a API) SetGroupRobotAddOption(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_robot_add_option", params)
	return err
}

// ---- 群相册 ----

// GetGroupAlbumList 获取群相册列表。
func (a API) GetGroupAlbumList(ctx context.Context, groupID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_group_album_list", H{"group_id": groupID})
}

// GetQunAlbumList 获取群相册列表（NapCat 风格分页）。
func (a API) GetQunAlbumList(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_qun_album_list", params)
}

// UploadImageToQunAlbum 上传图片到群相册。
func (a API) UploadImageToQunAlbum(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "upload_image_to_qun_album", params)
}

// UploadVideoToQunAlbum 上传视频到群相册。
func (a API) UploadVideoToQunAlbum(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "upload_video_to_qun_album", params)
}

// GetGroupAlbumMediaList 获取相册图片/视频列表（分页）。
func (a API) GetGroupAlbumMediaList(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_group_album_media_list", params)
}

// DoGroupAlbumComment 评论相册媒体。
func (a API) DoGroupAlbumComment(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "do_group_album_comment", params)
	return err
}

// SetGroupAlbumMediaLike 点赞相册媒体。
func (a API) SetGroupAlbumMediaLike(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_album_media_like", params)
	return err
}

// CancelGroupAlbumMediaLike 取消点赞相册媒体。
func (a API) CancelGroupAlbumMediaLike(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "cancel_group_album_media_like", params)
	return err
}

// DelGroupAlbumMedia 删除相册图片/视频。
func (a API) DelGroupAlbumMedia(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "del_group_album_media", params)
	return err
}

// ---- QQ 空间 ----

// GetQzoneMsgList 获取空间动态列表（自己的或目标用户的）。
func (a API) GetQzoneMsgList(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_qzone_msg_list", params)
}

// GetQzoneMsgDetail 获取动态详情（含一页评论）。
func (a API) GetQzoneMsgDetail(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_qzone_msg_detail", params)
}

// GetQzoneFeeds 获取好友动态流（结构化内容 + 游标）。
func (a API) GetQzoneFeeds(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_qzone_feeds", params)
}

// SendQzoneMsg 发布空间动态（文本/图片，权限）。
func (a API) SendQzoneMsg(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "send_qzone_msg", params)
}

// DeleteQzoneMsg 删除动态（按 tid）。
func (a API) DeleteQzoneMsg(ctx context.Context, tid string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "delete_qzone_msg", H{"tid": tid})
	return err
}

// SetQzoneMsgRight 修改动态可见权限。
func (a API) SetQzoneMsgRight(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_qzone_msg_right", params)
	return err
}

// LikeQzone 点赞空间动态。
func (a API) LikeQzone(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "like_qzone", params)
	return err
}

// UnlikeQzone 取消点赞空间动态。
func (a API) UnlikeQzone(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "unlike_qzone", params)
	return err
}

// CommentQzone 评论/回复空间动态（可带图片）。
func (a API) CommentQzone(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "comment_qzone", params)
	return err
}

// SetQzoneBan 在自己的空间黑名单中拉黑/解除拉黑。
func (a API) SetQzoneBan(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_qzone_ban", params)
	return err
}

// ---- 系统表情 ----

// FetchSysFaces 获取 QQ 系统表情目录（按包）。
func (a API) FetchSysFaces(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "fetch_sys_faces", params)
}

// FetchFaceEntity 按 face_id 获取单个表情。
func (a API) FetchFaceEntity(ctx context.Context, faceID int) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "fetch_face_entity", H{"face_id": faceID})
}

// SearchSysFaces 按 id/名称/别名/包搜索系统表情。
func (a API) SearchSysFaces(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "search_sys_faces", params)
}

// FetchSuperFaceID 判断某表情是否使用 super-face 格式。
func (a API) FetchSuperFaceID(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "fetch_super_face_id", params)
}

// ---- 流式接口 ----

// UploadFileStream 分块上传文件到 bot 本地路径（stream）。
func (a API) UploadFileStream(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "upload_file_stream", params)
}

// CleanStreamTempFile 清理流式上传/下载临时目录。
func (a API) CleanStreamTempFile(ctx context.Context) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "clean_stream_temp_file", H{})
	return err
}

// DownloadFileStream 流式下载文件（本地/URL/缓存媒体，分块）。
func (a API) DownloadFileStream(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "download_file_stream", params)
}

// DownloadFileImageStream 流式下载图片。
func (a API) DownloadFileImageStream(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "download_file_image_stream", params)
}

// DownloadFileRecordStream 流式下载语音。
func (a API) DownloadFileRecordStream(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "download_file_record_stream", params)
}

// TestDownloadStream 推送 10 帧测试数据验证流式传输。
func (a API) TestDownloadStream(ctx context.Context) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "test_download_stream", H{})
}

// ---- 其他扩展 ----

// SendCustomFace 发送账号自定义表情（emoji_id/MD5）作为图片。
func (a API) SendCustomFace(ctx context.Context, params H) (MessageID, error) {
	out, err := CallAPI[messageIDResult](a.call, ctx, "send_custom_face", params)
	return MessageID(out.MessageID), err
}

// GetGroupShareLink 获取群分享/邀请链接。
func (a API) GetGroupShareLink(ctx context.Context, groupID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_group_share_link", H{"group_id": groupID})
}

// SetGroupReaction 群聊表情回应。
func (a API) SetGroupReaction(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_reaction", params)
	return err
}

// FetchPttText 获取语音转文字结果（别名 get_ptt_text / get_record_text）。
func (a API) FetchPttText(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "fetch_ptt_text", params)
}

// SetFriendRemark 设置好友备注。
func (a API) SetFriendRemark(ctx context.Context, userID int64, remark string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_friend_remark", H{"user_id": userID, "remark": remark})
	return err
}

// SetGroupRemark 设置群备注。
func (a API) SetGroupRemark(ctx context.Context, groupID int64, remark string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_remark", H{"group_id": groupID, "remark": remark})
	return err
}

// SetDiyOnlineStatus 设置自定义在线状态。
func (a API) SetDiyOnlineStatus(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_diy_online_status", params)
	return err
}

// GetGroupIgnoredNotifies 获取被过滤的入群请求。
func (a API) GetGroupIgnoredNotifies(ctx context.Context, groupID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_group_ignored_notifies", H{"group_id": groupID})
}

// GetGroupIgnoreAddRequest 获取被忽略的入群请求（NapCat）。
func (a API) GetGroupIgnoreAddRequest(ctx context.Context, groupID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_group_ignore_add_request", H{"group_id": groupID})
}

// GetGroupSignedList 获取群今日打卡列表。
func (a API) GetGroupSignedList(ctx context.Context, groupID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_group_signed_list", H{"group_id": groupID})
}

// FetchCustomFaceDetail 获取自定义表情详情。
func (a API) FetchCustomFaceDetail(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "fetch_custom_face_detail", params)
}

// GetEmojiLikes 获取表情回应用户。
func (a API) GetEmojiLikes(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_emoji_likes", params)
}

// GetMsgEmojiLikes 获取一条消息的全部表情回应。
func (a API) GetMsgEmojiLikes(ctx context.Context, messageID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_msg_emoji_likes", H{"message_id": messageID})
}

// SetFriendsCategory 移动好友到指定分组。
func (a API) SetFriendsCategory(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_friends_category", params)
	return err
}

// GetUnidirectionalFriendList 获取单向好友列表。
func (a API) GetUnidirectionalFriendList(ctx context.Context) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_unidirectional_friend_list", H{})
}

// GetClientkey 获取 clientkey + 过期时间 + index。
func (a API) GetClientkey(ctx context.Context, domain string) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_clientkey", H{"domain": domain})
}

// GetGroupDetailInfo 获取群详细信息。
func (a API) GetGroupDetailInfo(ctx context.Context, groupID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_group_detail_info", H{"group_id": groupID})
}

// TransGroupFile 转存群文件。
func (a API) TransGroupFile(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "trans_group_file", params)
	return err
}

// BotExit 退出机器人。
func (a API) BotExit(ctx context.Context) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "bot_exit", H{})
	return err
}

// GetAIRecord 生成 AI 语音。
func (a API) GetAIRecord(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_ai_record", params)
}

// RequestDecryptKey 请求数据库解密密钥。
func (a API) RequestDecryptKey(ctx context.Context) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "request_decrypt_key", H{})
}

// GetRKeyServer 获取 rkey 服务器信息。
func (a API) GetRKeyServer(ctx context.Context) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_rkey_server", H{})
}

// SendPacket 发送原始 SSO 包（cmd + hex data）。
func (a API) SendPacket(ctx context.Context, cmd string, data string) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "send_packet", H{"cmd": cmd, "data": data})
}

// GetCollectionList 获取收藏列表。
func (a API) GetCollectionList(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_collection_list", params)
}

// GetFriendDress 获取指定 QQ 号正在使用的个性装扮。
func (a API) GetFriendDress(ctx context.Context, userID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "_get_friend_dress", H{"user_id": userID})
}

// UploadForwardMsg 上传合并转发资源。
func (a API) UploadForwardMsg(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "upload_forward_msg", params)
}

// ---- 群文件扩展 ----

// MoveGroupFile 在群文件夹间移动文件。
func (a API) MoveGroupFile(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "move_group_file", params)
	return err
}

// RenameGroupFile 重命名群文件。
func (a API) RenameGroupFile(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "rename_group_file", params)
	return err
}

// DeleteGroupFileFolder 删除群文件夹（SnowLuma 标准名，与 DeleteGroupFolder 等价）。
func (a API) DeleteGroupFileFolder(ctx context.Context, groupID int64, folderID string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "delete_group_file_folder", H{"group_id": groupID, "folder_id": folderID})
	return err
}

// RenameGroupFileFolder 重命名群文件夹。
func (a API) RenameGroupFileFolder(ctx context.Context, params H) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "rename_group_file_folder", params)
	return err
}

// GetPrivateFileURL 获取私聊文件下载链接。
func (a API) GetPrivateFileURL(ctx context.Context, params H) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_private_file_url", params)
}