snowluma/api.go

package snowluma

import "context"

// H 是裸调 action 时的参数表（配合 Context.Call / Client.Call 使用）。
type H = map[string]any

// API 聚合全部 OneBot 11 / go-cqhttp / NapCat 兼容 / SnowLuma 扩展 API 方法。
// Client 与 Context 均内嵌本类型；Client 走默认通道，
// Context 走产生当前事件的连接通道。ctx 传 nil 时用 30 秒超时。
type API struct {
	call Caller
}

// ---- 消息收发 ----

// messageIDResult 承接 send_* 类 API 返回的 data: {"message_id": ...}。
type messageIDResult struct {
	MessageID IntString `json:"message_id"`
}

// SendPrivateMsg 发送私聊消息，返回 message_id。
func (a API) SendPrivateMsg(ctx context.Context, userID int64, message ...Segment) (MessageID, error) {
	return a.sendMsg(ctx, "send_private_msg", H{"user_id": userID, "message": message})
}

// SendGroupMsg 发送群聊消息，返回 message_id。
func (a API) SendGroupMsg(ctx context.Context, groupID int64, message ...Segment) (MessageID, error) {
	return a.sendMsg(ctx, "send_group_msg", H{"group_id": groupID, "message": message})
}

// SendMsg 按消息类型发送，messageType 取值 private/group。
func (a API) SendMsg(ctx context.Context, messageType string, id int64, message ...Segment) (MessageID, error) {
	return a.sendMsg(ctx, "send_msg", H{"message_type": messageType, "user_id": id, "group_id": id, "message": message})
}

// SendPrivateMsgCQ 用 CQ 码字符串发送私聊消息。
func (a API) SendPrivateMsgCQ(ctx context.Context, userID int64, cqCode string) (MessageID, error) {
	return a.sendMsg(ctx, "send_private_msg", H{"user_id": userID, "message": cqCode})
}

// SendGroupMsgCQ 用 CQ 码字符串发送群聊消息。
func (a API) SendGroupMsgCQ(ctx context.Context, groupID int64, cqCode string) (MessageID, error) {
	return a.sendMsg(ctx, "send_group_msg", H{"group_id": groupID, "message": cqCode})
}

func (a API) sendMsg(ctx context.Context, action string, params H) (MessageID, error) {
	out, err := CallAPI[messageIDResult](a.call, ctx, action, params)
	return MessageID(out.MessageID), err
}

// DeleteMsg 撤回消息。
func (a API) DeleteMsg(ctx context.Context, messageID int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "delete_msg", H{"message_id": messageID})
	return err
}

// GetMessage 获取一条消息的完整内容。
func (a API) GetMessage(ctx context.Context, messageID int64) (MessageInfo, error) {
	return CallAPI[MessageInfo](a.call, ctx, "get_msg", H{"message_id": messageID})
}

// GetForwardMsg 获取合并转发的子消息列表。
func (a API) GetForwardMsg(ctx context.Context, messageID int64) (ForwardMessages, error) {
	return CallAPI[ForwardMessages](a.call, ctx, "get_forward_msg", H{"message_id": messageID})
}

// SendLike 给好友点赞，times 为次数（每日上限内）。
func (a API) SendLike(ctx context.Context, userID int64, times int) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "send_like", H{"user_id": userID, "times": times})
	return err
}

// MarkMsgAsRead 标记单条消息已读。
func (a API) MarkMsgAsRead(ctx context.Context, messageID int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "mark_msg_as_read", H{"message_id": messageID})
	return err
}

// MarkPrivateMsgAsRead 标记私聊会话已读。
func (a API) MarkPrivateMsgAsRead(ctx context.Context, userID int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "mark_private_msg_as_read", H{"user_id": userID})
	return err
}

// MarkGroupMsgAsRead 标记群消息已读。
func (a API) MarkGroupMsgAsRead(ctx context.Context, groupID int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "mark_group_msg_as_read", H{"group_id": groupID})
	return err
}

// MarkAllAsRead 标记全部会话已读。
func (a API) MarkAllAsRead(ctx context.Context) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "_mark_all_as_read", H{})
	return err
}

// SetMsgEmojiLike 给消息贴表情回应。
func (a API) SetMsgEmojiLike(ctx context.Context, messageID int64, faceID int) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_msg_emoji_like", H{"message_id": messageID, "face_id": faceID})
	return err
}

// ---- 合并转发 ----

// Node 定义一个合并转发节点：MessageID>0 时引用已有消息，否则用 UserID/Nickname/Content 伪造。
type Node struct {
	MessageID int64
	UserID    int64
	Nickname  string
	Content   []Segment
}

func (n Node) segment() Segment {
	if n.MessageID != 0 {
		return NodeSeg(n.MessageID)
	}
	return CustomNode(n.UserID, n.Nickname, n.Content)
}

func nodesPayload(nodes []Node) []Segment {
	segs := make([]Segment, 0, len(nodes))
	for _, n := range nodes {
		segs = append(segs, n.segment())
	}
	return segs
}

// SendGroupForwardMsg 发送群合并转发消息。
func (a API) SendGroupForwardMsg(ctx context.Context, groupID int64, nodes ...Node) (SendForwardResult, error) {
	return CallAPI[SendForwardResult](a.call, ctx, "send_group_forward_msg", H{"group_id": groupID, "messages": nodesPayload(nodes)})
}

// SendPrivateForwardMsg 发送私聊合并转发消息。
func (a API) SendPrivateForwardMsg(ctx context.Context, userID int64, nodes ...Node) (SendForwardResult, error) {
	return CallAPI[SendForwardResult](a.call, ctx, "send_private_forward_msg", H{"user_id": userID, "messages": nodesPayload(nodes)})
}

// SendForwardMsg 通过 NapCat 扩展接口发送合并转发（同时适用于群与私聊场景的构造）。
func (a API) SendForwardMsg(ctx context.Context, nodes ...Node) (SendForwardResult, error) {
	return CallAPI[SendForwardResult](a.call, ctx, "send_forward_msg", H{"messages": nodesPayload(nodes)})
}

// ForwardFriendSingleMsg 把一条已有消息转发给好友。
func (a API) ForwardFriendSingleMsg(ctx context.Context, userID, messageID int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "forward_friend_single_msg", H{"user_id": userID, "message_id": messageID})
	return err
}

// ForwardGroupSingleMsg 把一条已有消息转发到群。
func (a API) ForwardGroupSingleMsg(ctx context.Context, groupID, messageID int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "forward_group_single_msg", H{"group_id": groupID, "message_id": messageID})
	return err
}

// ---- 历史消息 ----

// GetFriendMsgHistory 拉取好友历史消息。messageSeq 传 0 表示从最新开始。
func (a API) GetFriendMsgHistory(ctx context.Context, userID, messageSeq int64, count int) (HistoryMessages, error) {
	return CallAPI[HistoryMessages](a.call, ctx, "get_friend_msg_history", H{"user_id": userID, "message_seq": messageSeq, "count": count})
}

// GetGroupMsgHistory 拉取群历史消息。messageSeq 传 0 表示从最新开始。
func (a API) GetGroupMsgHistory(ctx context.Context, groupID, messageSeq int64, count int, reverse bool) (HistoryMessages, error) {
	return CallAPI[HistoryMessages](a.call, ctx, "get_group_msg_history", H{"group_id": groupID, "message_seq": messageSeq, "count": count, "reverse": reverse})
}

// ---- 好友与群信息 ----

// GetLoginInfo 获取登录号信息。
func (a API) GetLoginInfo(ctx context.Context) (LoginInfo, error) {
	return CallAPI[LoginInfo](a.call, ctx, "get_login_info", H{})
}

// GetStrangerInfo 获取陌生人信息。
func (a API) GetStrangerInfo(ctx context.Context, userID int64, noCache bool) (StrangerInfo, error) {
	return CallAPI[StrangerInfo](a.call, ctx, "get_stranger_info", H{"user_id": userID, "no_cache": noCache})
}

// GetFriendList 获取好友列表。
func (a API) GetFriendList(ctx context.Context) ([]FriendInfo, error) {
	return CallAPI[[]FriendInfo](a.call, ctx, "get_friend_list", H{})
}

// GetFriendsWithCategory 获取分类好友列表（NapCat 兼容）。
func (a API) GetFriendsWithCategory(ctx context.Context) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_friends_with_category", H{})
}

// DeleteFriend 删除好友。
func (a API) DeleteFriend(ctx context.Context, userID int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "delete_friend", H{"user_id": userID})
	return err
}

// GetGroupInfo 获取群信息。
func (a API) GetGroupInfo(ctx context.Context, groupID int64) (GroupInfo, error) {
	return CallAPI[GroupInfo](a.call, ctx, "get_group_info", H{"group_id": groupID})
}

// GetGroupInfoEx 获取群扩展信息（NapCat 兼容）。
func (a API) GetGroupInfoEx(ctx context.Context, groupID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_group_info_ex", H{"group_id": groupID})
}

// GetGroupList 获取群列表。
func (a API) GetGroupList(ctx context.Context) ([]GroupInfo, error) {
	return CallAPI[[]GroupInfo](a.call, ctx, "get_group_list", H{})
}

// GetGroupMemberInfo 获取群成员信息。
func (a API) GetGroupMemberInfo(ctx context.Context, groupID, userID int64, noCache bool) (GroupMemberInfo, error) {
	return CallAPI[GroupMemberInfo](a.call, ctx, "get_group_member_info", H{"group_id": groupID, "user_id": userID, "no_cache": noCache})
}

// GetGroupMemberList 获取群成员列表。
func (a API) GetGroupMemberList(ctx context.Context, groupID int64) ([]GroupMemberInfo, error) {
	return CallAPI[[]GroupMemberInfo](a.call, ctx, "get_group_member_list", H{"group_id": groupID})
}

// GetGroupHonorInfo 获取群荣誉信息，honorType 取值 talky/performer/legend/strong_newbie/emotion/all。
func (a API) GetGroupHonorInfo(ctx context.Context, groupID int64, honorType string) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_group_honor_info", H{"group_id": groupID, "type": honorType})
}

// ---- 群管理 ----

// SetGroupKick 踢出群成员，rejectAddRequest 表示同时拒绝其再次加群。
func (a API) SetGroupKick(ctx context.Context, groupID, userID int64, rejectAddRequest bool) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_kick", H{"group_id": groupID, "user_id": userID, "reject_add_request": rejectAddRequest})
	return err
}

// SetGroupBan 禁言群成员，duration 为秒数，0 表示解除禁言。
func (a API) SetGroupBan(ctx context.Context, groupID, userID, duration int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_ban", H{"group_id": groupID, "user_id": userID, "duration": duration})
	return err
}

// SetGroupWholeBan 全员禁言。
func (a API) SetGroupWholeBan(ctx context.Context, groupID int64, enable bool) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_whole_ban", H{"group_id": groupID, "enable": enable})
	return err
}

// SetGroupAdmin 设置/取消群管理员。
func (a API) SetGroupAdmin(ctx context.Context, groupID, userID int64, enable bool) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_admin", H{"group_id": groupID, "user_id": userID, "enable": enable})
	return err
}

// SetGroupCard 设置群名片。
func (a API) SetGroupCard(ctx context.Context, groupID, userID int64, card string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_card", H{"group_id": groupID, "user_id": userID, "card": card})
	return err
}

// SetGroupName 设置群名。
func (a API) SetGroupName(ctx context.Context, groupID int64, name string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_name", H{"group_id": groupID, "group_name": name})
	return err
}

// SetGroupLeave 退群，dismiss 仅群主可用（解散群）。
func (a API) SetGroupLeave(ctx context.Context, groupID int64, dismiss bool) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_leave", H{"group_id": groupID, "is_dismiss": dismiss})
	return err
}

// SetGroupSpecialTitle 设置群专属头衔。
func (a API) SetGroupSpecialTitle(ctx context.Context, groupID, userID int64, title string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_special_title", H{"group_id": groupID, "user_id": userID, "special_title": title})
	return err
}

// SetGroupPortrait 设置群头像。
func (a API) SetGroupPortrait(ctx context.Context, groupID int64, file string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_portrait", H{"group_id": groupID, "file": file})
	return err
}

// SetGroupSign 群签到（go-cqhttp 兼容）。
func (a API) SetGroupSign(ctx context.Context, groupID int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_sign", H{"group_id": groupID})
	return err
}

// SendGroupSign 发送群签到（NapCat 兼容）。
func (a API) SendGroupSign(ctx context.Context, groupID int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "send_group_sign", H{"group_id": groupID})
	return err
}

// GetGroupAtAllRemain 获取剩余 @全体成员 次数。
func (a API) GetGroupAtAllRemain(ctx context.Context, groupID int64) (AtAllRemain, error) {
	return CallAPI[AtAllRemain](a.call, ctx, "get_group_at_all_remain", H{"group_id": groupID})
}

// GetGroupShutList 获取群禁言列表（NapCat 兼容）。
func (a API) GetGroupShutList(ctx context.Context, groupID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_group_shut_list", H{"group_id": groupID})
}

// ---- 戳一戳 / 状态 ----

// SendPoke 戳一戳（群聊场景）。
func (a API) SendPoke(ctx context.Context, groupID, userID int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "send_poke", H{"group_id": groupID, "user_id": userID})
	return err
}

// FriendPoke 戳好友。
func (a API) FriendPoke(ctx context.Context, userID int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "friend_poke", H{"user_id": userID})
	return err
}

// GroupPoke 在群里戳某人。
func (a API) GroupPoke(ctx context.Context, groupID, userID int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "group_poke", H{"group_id": groupID, "user_id": userID})
	return err
}

// SetInputStatus 设置好友会话的「正在输入」等状态，eventType 取值 1(文字)/2(语音)/3(视频)/4(文件)。
func (a API) SetInputStatus(ctx context.Context, userID int64, eventType int) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_input_status", H{"user_id": userID, "event_type": eventType})
	return err
}

// SetOnlineStatus 设置在线状态（NapCat 兼容）。
func (a API) SetOnlineStatus(ctx context.Context, statusID, extCode int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_online_status", H{"status": statusID, "ext_status": extCode})
	return err
}

// SetSelfLongNick 设置签名/长昵称。
func (a API) SetSelfLongNick(ctx context.Context, longNick string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_self_longnick", H{"long_nick": longNick})
	return err
}

// GetUserStatus 获取用户在线状态（NapCat 兼容）。
func (a API) GetUserStatus(ctx context.Context, userID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "nc_get_user_status", H{"user_id": userID})
}

// GetPacketStatus 获取 SnowLuma 底层包状态（NapCat 兼容）。
func (a API) GetPacketStatus(ctx context.Context) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "nc_get_packet_status", H{})
}

// GetProfileLike 获取用户被点赞信息（NapCat 兼容）。
func (a API) GetProfileLike(ctx context.Context, userID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_profile_like", H{"user_id": userID})
}

// ---- 请求处理 ----

// SetFriendAddRequest 处理加好友请求，approve 为是否同意，remark 为好友备注。
func (a API) SetFriendAddRequest(ctx context.Context, flag string, approve bool, remark string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_friend_add_request", H{"flag": flag, "approve": approve, "remark": remark})
	return err
}

// SetGroupAddRequest 处理加群/入群邀请，subType 取值 add/invite，reason 为拒绝理由。
func (a API) SetGroupAddRequest(ctx context.Context, flag, subType string, approve bool, reason string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_group_add_request", H{"flag": flag, "sub_type": subType, "approve": approve, "reason": reason})
	return err
}

// ---- 文件 ----

// UploadGroupFile 上传群文件，folderID 传空串则上传到根目录。
func (a API) UploadGroupFile(ctx context.Context, groupID int64, file, name, folderID string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "upload_group_file", H{"group_id": groupID, "file": file, "name": name, "folder_id": folderID})
	return err
}

// UploadPrivateFile 上传私聊文件。
func (a API) UploadPrivateFile(ctx context.Context, userID int64, file, name string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "upload_private_file", H{"user_id": userID, "file": file, "name": name})
	return err
}

// DeleteGroupFile 删除群文件。
func (a API) DeleteGroupFile(ctx context.Context, groupID int64, fileID string, busID int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "delete_group_file", H{"group_id": groupID, "file_id": fileID, "busid": busID})
	return err
}

// DeleteGroupFolder 删除群文件夹。
func (a API) DeleteGroupFolder(ctx context.Context, groupID int64, folderID string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "delete_group_folder", H{"group_id": groupID, "folder_id": folderID})
	return err
}

// CreateGroupFileFolder 创建群文件夹，parentID 传 "/" 表示根目录。
func (a API) CreateGroupFileFolder(ctx context.Context, groupID int64, name, parentID string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "create_group_file_folder", H{"group_id": groupID, "name": name, "parent_id": parentID})
	return err
}

// GetGroupFileSystemInfo 获取群文件系统信息。
func (a API) GetGroupFileSystemInfo(ctx context.Context, groupID int64) (FileSystemInfo, error) {
	return CallAPI[FileSystemInfo](a.call, ctx, "get_group_file_system_info", H{"group_id": groupID})
}

// GetGroupRootFiles 获取群根目录文件列表。
func (a API) GetGroupRootFiles(ctx context.Context, groupID int64) (FileList, error) {
	return CallAPI[FileList](a.call, ctx, "get_group_root_files", H{"group_id": groupID})
}

// GetGroupFilesByFolder 获取群指定文件夹内的文件列表。
func (a API) GetGroupFilesByFolder(ctx context.Context, groupID int64, folderID string) (FileList, error) {
	return CallAPI[FileList](a.call, ctx, "get_group_files_by_folder", H{"group_id": groupID, "folder_id": folderID})
}

// GetGroupFileURL 获取群文件下载链接。
func (a API) GetGroupFileURL(ctx context.Context, groupID int64, fileID string, busID int64) (string, error) {
	out, err := CallAPI[struct {
		URL string `json:"url"`
	}](a.call, ctx, "get_group_file_url", H{"group_id": groupID, "file_id": fileID, "busid": busID})
	return out.URL, err
}

// DownloadFile 通过 SnowLuma 下载文件到本地，headers 形如 ["Cookie: a=1"]。
func (a API) DownloadFile(ctx context.Context, url string, headers []string, threadCount int) (DownloadedFile, error) {
	return CallAPI[DownloadedFile](a.call, ctx, "download_file", H{"url": url, "headers": headers, "thread_cnt": threadCount})
}

// GetFile 获取已收到的文件（消息段里的 file_id），返回本地缓存路径。
func (a API) GetFile(ctx context.Context, fileID string) (DownloadedFile, error) {
	return CallAPI[DownloadedFile](a.call, ctx, "get_file", H{"file_id": fileID})
}

// CheckURLSafely 检查 URL 安全等级（1 安全 2 危险 3 未验证）。
func (a API) CheckURLSafely(ctx context.Context, url string) (URLSafety, error) {
	return CallAPI[URLSafety](a.call, ctx, "check_url_safely", H{"url": url})
}

// OCRImage 对图片执行 OCR（NapCat 兼容）。
func (a API) OCRImage(ctx context.Context, image string) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "ocr_image", H{"image": image})
}

// ---- 媒体 ----

// GetImage 获取图片信息（本地缓存路径与 URL）。
func (a API) GetImage(ctx context.Context, file string) (ImageResult, error) {
	return CallAPI[ImageResult](a.call, ctx, "get_image", H{"file": file})
}

// GetRecord 获取语音并转换为指定格式（如 "mp3"、"amr"）。
func (a API) GetRecord(ctx context.Context, file, outFormat string) (RecordResult, error) {
	return CallAPI[RecordResult](a.call, ctx, "get_record", H{"file": file, "out_format": outFormat})
}

// CanSendImage 检查能否发送图片。
func (a API) CanSendImage(ctx context.Context) (bool, error) {
	return CallAPI[bool](a.call, ctx, "can_send_image", H{})
}

// CanSendRecord 检查能否发送语音。
func (a API) CanSendRecord(ctx context.Context) (bool, error) {
	return CallAPI[bool](a.call, ctx, "can_send_record", H{})
}

// FetchCustomFace 拉取自定义表情（NapCat 兼容）。
func (a API) FetchCustomFace(ctx context.Context, count int) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "fetch_custom_face", H{"count": count})
}

// FetchEmojiLike 拉取表情联动搜索结果（NapCat 兼容）。
func (a API) FetchEmojiLike(ctx context.Context, keyword string, page int) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "fetch_emoji_like", H{"key": keyword, "page_no": page, "page_size": 20})
}

// GetAICharacters 获取 AI 语音角色列表（NapCat 兼容）。
func (a API) GetAICharacters(ctx context.Context) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_ai_characters", H{})
}

// SendGroupAIRecord 发送群 AI 语音（NapCat 兼容）。
func (a API) SendGroupAIRecord(ctx context.Context, groupID int64, character, text string) (MessageID, error) {
	out, err := CallAPI[messageIDResult](a.call, ctx, "send_group_ai_record", H{"group_id": groupID, "character": character, "text": text})
	return MessageID(out.MessageID), err
}

// GetMiniAppArk 生成小程序卡片 JSON（NapCat 兼容）。
func (a API) GetMiniAppArk(ctx context.Context, kind, jsonPayload string) (MiniAppArk, error) {
	return CallAPI[MiniAppArk](a.call, ctx, "get_mini_app_ark", H{"kind": kind, "json": jsonPayload})
}

// ArkShareGroup 生成群分享卡片。
// napcat 里这个动作名是 NapCat 私有的 "ArkShareGroup"，SnowLuma 使用
// NapCat 标准名 "send_group_ark_share"，此处做了别名适配，同名方法可直接用。
func (a API) ArkShareGroup(ctx context.Context, groupID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "send_group_ark_share", H{"group_id": groupID})
}

// ArkSharePeer 生成单聊分享卡片。
// 同 ArkShareGroup：napcat 的 "ArkSharePeer" 在 SnowLuma 里是 "send_ark_share"。
func (a API) ArkSharePeer(ctx context.Context, userID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "send_ark_share", H{"user_id": userID})
}

// TranslateEn2Zh 英译中（NapCat 兼容）。
func (a API) TranslateEn2Zh(ctx context.Context, words []string) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "translate_en2zh", H{"words": words})
}

// GetRKey 获取图片 rkey（NapCat 兼容）。
func (a API) GetRKey(ctx context.Context) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "nc_get_rkey", H{})
}

// ---- 系统与凭证 ----

// GetStatus 获取运行状态。
func (a API) GetStatus(ctx context.Context) (Status, error) {
	return CallAPI[Status](a.call, ctx, "get_status", H{})
}

// GetVersionInfo 获取版本信息。
func (a API) GetVersionInfo(ctx context.Context) (VersionInfo, error) {
	return CallAPI[VersionInfo](a.call, ctx, "get_version_info", H{})
}

// CleanCache 清理缓存。
func (a API) CleanCache(ctx context.Context) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "clean_cache", H{})
	return err
}

// SetRestart 重启 OneBot 实现（SnowLuma 可能不支持）。
func (a API) SetRestart(ctx context.Context, delayMS int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_restart", H{"delay": delayMS})
	return err
}

// GetCookies 获取指定域名的 Cookies。
func (a API) GetCookies(ctx context.Context, domain string) (Cookies, error) {
	return CallAPI[Cookies](a.call, ctx, "get_cookies", H{"domain": domain})
}

// GetCSRFToken 获取 CSRF Token。
func (a API) GetCSRFToken(ctx context.Context) (CSRFToken, error) {
	return CallAPI[CSRFToken](a.call, ctx, "get_csrf_token", H{})
}

// GetCredentials 获取 Cookies 与 CSRF Token。
func (a API) GetCredentials(ctx context.Context, domain string) (Credentials, error) {
	return CallAPI[Credentials](a.call, ctx, "get_credentials", H{"domain": domain})
}

// GetOnlineClients 获取账号在其他端的在线客户端。
func (a API) GetOnlineClients(ctx context.Context, noCache bool) (OnlineClients, error) {
	return CallAPI[OnlineClients](a.call, ctx, "get_online_clients", H{"no_cache": noCache})
}

// SetQQProfile 设置登录号资料。
func (a API) SetQQProfile(ctx context.Context, nickname, company, email, college, personalNote string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_qq_profile", H{
		"nickname": nickname, "company": company, "email": email,
		"college": college, "personal_note": personalNote,
	})
	return err
}

// SetQQAvatar 设置登录号头像。
func (a API) SetQQAvatar(ctx context.Context, file string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_qq_avatar", H{"file": file})
	return err
}

// GetModelShow 获取在线机型展示（go-cqhttp 兼容）。
func (a API) GetModelShow(ctx context.Context, model string) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "_get_model_show", H{"model": model})
}

// SetModelShow 设置在线机型展示（go-cqhttp 兼容）。
func (a API) SetModelShow(ctx context.Context, model, modelShow string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "_set_model_show", H{"model": model, "model_show": modelShow})
	return err
}

// GetRobotUinRange 获取官方机器人号段（NapCat 兼容）。
func (a API) GetRobotUinRange(ctx context.Context) (RobotUinRanges, error) {
	return CallAPI[RobotUinRanges](a.call, ctx, "get_robot_uin_range", H{})
}

// GetRecentContact 获取最近联系人列表（NapCat 兼容）。
func (a API) GetRecentContact(ctx context.Context, count int) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_recent_contact", H{"count": count})
}

// ---- 精华消息 ----

// GetEssenceMsgList 获取群精华消息列表。
func (a API) GetEssenceMsgList(ctx context.Context, groupID int64) ([]EssenceMessage, error) {
	return CallAPI[[]EssenceMessage](a.call, ctx, "get_essence_msg_list", H{"group_id": groupID})
}

// SetEssenceMsg 设置精华消息。
func (a API) SetEssenceMsg(ctx context.Context, messageID int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "set_essence_msg", H{"message_id": messageID})
	return err
}

// DeleteEssenceMsg 移除精华消息。
func (a API) DeleteEssenceMsg(ctx context.Context, messageID int64) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "delete_essence_msg", H{"message_id": messageID})
	return err
}

// ---- 群公告 ----

// SendGroupNotice 发布群公告（go-cqhttp 兼容 _send_group_notice）。
func (a API) SendGroupNotice(ctx context.Context, groupID int64, text, image string) error {
	params := H{"group_id": groupID, "content": text}
	if image != "" {
		params["image"] = image
	}
	_, err := CallAPI[jsonNull](a.call, ctx, "_send_group_notice", params)
	return err
}

// GetGroupNotice 获取群公告列表（go-cqhttp 兼容 _get_group_notice）。
func (a API) GetGroupNotice(ctx context.Context, groupID int64) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "_get_group_notice", H{"group_id": groupID})
}

// DelGroupNotice 删除群公告（NapCat 兼容 _del_group_notice）。
func (a API) DelGroupNotice(ctx context.Context, groupID int64, noticeID string) error {
	_, err := CallAPI[jsonNull](a.call, ctx, "_del_group_notice", H{"group_id": groupID, "notice_id": noticeID})
	return err
}

// ---- 群系统消息 ----

// GetGroupSystemMsg 获取加群邀请等系统消息。
func (a API) GetGroupSystemMsg(ctx context.Context) (jsonRaw, error) {
	return CallAPI[jsonRaw](a.call, ctx, "get_group_system_msg", H{})
}

// jsonRaw 承接未结构化的扩展 API 返回。
type jsonRaw map[string]any

// jsonNull 用于不需要返回值的 action。
type jsonNull = struct{}