botcore

type Attachment struct {
	Type AttachmentType // 附件类型: image/file
	URL  string         // 可下载的资源地址（当 Data 为空时使用）
	// Data 存储已解密/已下载的原始字节数据。
	// 当此字段非空时，SaveAttachments 将直接使用此数据而不是下载 URL。
	// 由平台协议层（如 wecom）自动填充已解密的附件数据。
	Data []byte
}

type AttachmentType string

type Bot interface {
	// BuildFirstSnapshot 生成首包快照。
	BuildFirstSnapshot(raw any) (RequestSnapshot, error)

	// BuildReply 将流式片段编码为平台响应。
	BuildReply(firstSnapshot RequestSnapshot, chunk StreamChunk) (any, error)

	// Response 向指定的 response_url 发送主动回复消息。
	Response(responseURL string, msg any) error

	// ResponseMarkdown 发送 Markdown 消息。
	ResponseMarkdown(responseURL, content string) error

	// ResponseTemplateCard 发送模板卡片消息。
	ResponseTemplateCard(responseURL string, card any) error
}

type Chain struct {
	// contains filtered or unexported fields
}

type ChatType string

type Matcher func(update RequestSnapshot) bool

type PipelineContext struct {
	Snapshot  RequestSnapshot
	Responser Responser
}

type PipelineFunc func(ctx PipelineContext) <-chan StreamChunk

type PipelineInvoker interface {
	Trigger(ctx PipelineContext) <-chan StreamChunk
}

type RequestSnapshot struct {
	ID       string   // 平台内的唯一消息、事件或流会话 ID
	SenderID string   // 触发用户标识
	ChatID   string   // 会话 ID（群、私聊等）
	ChatType ChatType // 会话类型，示例：single/chatroom（企业微信为 single/group，内部映射为 chatroom）

	Text        string            // 主要文本内容（若适用）
	Attachments []Attachment      // 标准化附件列表（图片/文件等）
	Raw         any               // 平台原始结构引用，便于 Pipeline 深度使用
	ResponseURL string            // 主动回复 URL（部分平台返回）
	Metadata    map[string]string // 扩展键值，如语言、平台等
}

type Responser interface {
	Response(responseURL string, msg any) error
	ResponseMarkdown(responseURL, content string) error
	ResponseTemplateCard(responseURL string, card any) error
}

type Route struct {
	Name    string
	Matcher Matcher
	Handler PipelineInvoker
}

type SavedAttachment struct {
	Attachment Attachment // 原始附件信息
	Path       string     // 保存后的本地路径
	Err        error      // 单个附件的错误（若有）
}

type StreamChunk struct {
	Content string
	Payload any // 扩展：支持携带复杂对象（如 TemplateCard），用于非流式回复
	IsFinal bool
}