bot

type Adapter interface {
	// Platform 返回平台标识。
	Platform() Platform

	// Start 启动适配器，连接平台 gateway。
	Start(ctx context.Context) error

	// Stop 优雅关闭适配器。
	Stop() error

	// Send 发送一条出站消息。
	Send(ctx context.Context, msg OutboundMessage) (SendResult, error)

	// SendTyping 发送"正在输入"状态。
	SendTyping(ctx context.Context, chatID string) error

	// Messages 返回入站消息通道。
	Messages() <-chan InboundMessage

	// Name 返回适配器实例名（用于日志）。
	Name() string
}

type AllowlistConfig struct {
	Enabled  bool
	AllowAll bool
	Mode     string // "open"（自动加入）| "review"（需审批）
	Users    map[Platform][]string
	Groups   map[Platform][]string
}

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

type ChannelConfig struct {
	Model         string
	WorkspaceRoot string
}

type ChatType string

type GatewayConfig struct {
	Model         string
	MaxSteps      int
	WorkspaceRoot string
	Channels      map[Platform]ChannelConfig
	Allowlist     AllowlistConfig
	Enabled       map[Platform]bool
	Debounce      time.Duration
	// SessionIdleTimeout controls how long a bot session can sit idle (no
	// incoming messages) before its controller is closed to reclaim memory.
	// A busy bot serving many users/-groups would otherwise keep every
	// controller alive forever. Default 30m; 0 disables reaping.
	SessionIdleTimeout time.Duration
	// AllowlistSaver 当新用户被自动加入白名单时调用，用于持久化。
	// 参数为更新后的完整 AllowlistConfig。nil 表示不持久化。
	AllowlistSaver func(AllowlistConfig)
	// OnTurnFinished 在一轮对话结束后调用（无论成功或出错），用于让上层（desktop）
	// 把对话方的远端 ID（如飞书 open_id）和本次会话的本地 transcript 路径回写到
	// BotConnection 的 SessionMappings —— 否则只有手动「测试连接」才记录 remoteID、
	// 而 SessionID（本地话题）永远为空，UI 显示「等待首条消息」。放在 turn 结束后
	// 是因为 sessionPath 要等首轮 RunTurn 才确定（prewarm 时为空）。nil 表示不回写。
	OnTurnFinished func(plat Platform, remoteID, sessionPath string)
}

type InboundMessage struct {
	Platform  Platform `json:"platform"`
	ChatType  ChatType `json:"chat_type"`
	ChatID    string   `json:"chat_id"`
	UserID    string   `json:"user_id"`
	UserName  string   `json:"user_name"`
	Text      string   `json:"text"`
	MessageID string   `json:"message_id"`
	ThreadID  string   `json:"thread_id,omitempty"`
	MediaURLs []string `json:"media_urls,omitempty"`
	Raw       any      `json:"-"`
}

type InlineKeyboard struct {
	Rows []InlineKeyboardRow `json:"rows"`
}

type InlineKeyboardButton struct {
	ID         string `json:"id"`
	Label      string `json:"label"`
	Style      int    `json:"style,omitempty"` // 0=default, 1=primary, 2=danger
	CallbackID string `json:"callback_id,omitempty"`
}

type InlineKeyboardRow struct {
	Buttons []InlineKeyboardButton `json:"buttons"`
}

type InteractiveCard struct {
	Header   string                   `json:"header"`
	Elements []InteractiveCardElement `json:"elements"`
}

type InteractiveCardElement struct {
	Tag     string         `json:"tag"`
	Content string         `json:"content,omitempty"`
	Extra   map[string]any `json:"extra,omitempty"`
}

type MessageHandler func(ctx context.Context, msg InboundMessage)

type OutboundMessage struct {
	ChatID       string           `json:"chat_id"`
	ChatType     ChatType         `json:"chat_type,omitempty"`
	Text         string           `json:"text,omitempty"`
	MediaURLs    []string         `json:"media_urls,omitempty"`
	ReplyToMsgID string           `json:"reply_to_msg_id,omitempty"`
	Keyboard     *InlineKeyboard  `json:"keyboard,omitempty"`
	Card         *InteractiveCard `json:"card,omitempty"`
}

type Platform string

type RecentChat struct {
	Platform Platform `json:"platform"`
	ChatType ChatType `json:"chatType"`
	ChatID   string   `json:"chatId"`
	UserName string   `json:"userName"`
	LastSeen int64    `json:"lastSeen"` // unix seconds
}

type SendResult struct {
	MessageID string `json:"message_id,omitempty"`
	Err       error  `json:"err,omitempty"`
}

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

type SessionSource struct {
	Platform Platform `json:"platform"`
	ChatType ChatType `json:"chat_type"`
	ChatID   string   `json:"chat_id"`
	UserID   string   `json:"user_id"`
	ThreadID string   `json:"thread_id,omitempty"`
}