Documentation
¶
Overview ¶
Package weclawbot 提供微信 ClawBot 的二维码登录、持续消息接收和文本消息发送能力。
SDK 不持久化 Bot Token、二维码、验证码或消息上下文。调用方负责安全保存登录结果, 并在回复消息时把 ReceiveMessages 返回的 from_user_id 和 context_token 传给 SendText。 媒体上传、下载、加解密和媒体消息发送不在当前支持范围内。
Index ¶
- Variables
- func IsSessionExpired(err error) bool
- type Client
- func (c *Client) GetQRCode(ctx context.Context, request GetQRCodeRequest) (*GetQRCodeResponse, error)
- func (c *Client) GetQRCodeStatus(ctx context.Context, request GetQRCodeStatusRequest) (*GetQRCodeStatusResponse, error)
- func (c *Client) GetUpdates(ctx context.Context, request GetUpdatesRequest) (*GetUpdatesResponse, error)
- func (c *Client) ReceiveMessages(ctx context.Context, handler func(context.Context, Message) error) error
- func (c *Client) SendText(ctx context.Context, request SendTextRequest) (*SendTextResponse, error)
- type GetQRCodeRequest
- type GetQRCodeResponse
- type GetQRCodeStatusRequest
- type GetQRCodeStatusResponse
- type GetUpdatesRequest
- type GetUpdatesResponse
- type Message
- type MessageID
- type MessageItem
- type MessageItemType
- type MessageState
- type MessageType
- type Option
- func WithBaseURL(u string) Option
- func WithBotAgent(agent string) Option
- func WithChannelVersion(version string) Option
- func WithClient(cli *restx.Client) Option
- func WithInsecureHTTP() Option
- func WithLongPollTimeout(timeout time.Duration) Option
- func WithRouteTag(routeTag string) Option
- func WithTimeout(timeout time.Duration) Option
- func WithToken(token string) Option
- type QRCodeStatus
- type SendTextRequest
- type SendTextResponse
- type TextItem
Constants ¶
This section is empty.
Variables ¶
var ( // ErrTokenRequired 表示当前操作必须提供二维码登录取得的 Bot Token。 ErrTokenRequired = errx.New("bot token is required") // ErrQRCodeRequired 表示二维码状态查询缺少二维码值。 ErrQRCodeRequired = errx.New("qrcode is required") // ErrQRCodeContentRequired 表示二维码响应缺少可供编码展示的内容。 ErrQRCodeContentRequired = errx.New("qrcode content is required") // ErrWriterRequired 表示二维码输出缺少目标 Writer。 ErrWriterRequired = errx.New("writer is required") // ErrUserIDRequired 表示文本消息缺少目标用户 ID。 ErrUserIDRequired = errx.New("user id is required") // ErrTextRequired 表示文本消息内容为空。 ErrTextRequired = errx.New("text is required") // ErrMessageHandlerRequired 表示持续接收消息时缺少消息处理函数。 ErrMessageHandlerRequired = errx.New("message handler is required") // ErrTooManyLocalTokens 表示二维码请求携带了超过协议上限的本地 Token。 ErrTooManyLocalTokens = errx.New("too many local tokens") // ErrInvalidURL 表示 API 地址或重定向地址不安全或无效。 ErrInvalidURL = errx.New("invalid api url") // ErrRequest 表示请求未获得有效 HTTP 响应,底层错误可能包含敏感查询参数而不会透出。 ErrRequest = errx.New("wechat request failed") // ErrHTTPStatus 表示微信接口返回了非成功 HTTP 状态。 ErrHTTPStatus = errx.New("unexpected http status") // ErrProtocol 表示微信接口响应缺失必要字段或返回业务错误。 ErrProtocol = errx.New("wechat protocol error") // ErrSessionExpired 表示 Bot Token 已失效,需要重新登录。 ErrSessionExpired = errx.New("wechat session expired") )
Functions ¶
func IsSessionExpired ¶
IsSessionExpired 判断 getUpdates 是否返回需要重新登录的会话失效错误。
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client 是微信 ClawBot HTTP JSON 协议客户端。
func (*Client) GetQRCode ¶
func (c *Client) GetQRCode(ctx context.Context, request GetQRCodeRequest) (*GetQRCodeResponse, error)
GetQRCode 获取微信登录二维码。该请求始终使用微信固定登录入口。
func (*Client) GetQRCodeStatus ¶
func (c *Client) GetQRCodeStatus(ctx context.Context, request GetQRCodeStatusRequest) (*GetQRCodeStatusResponse, error)
GetQRCodeStatus 执行一次二维码状态长轮询。内部超时返回 wait,调用方取消返回错误。
func (*Client) GetUpdates ¶
func (c *Client) GetUpdates(ctx context.Context, request GetUpdatesRequest) (*GetUpdatesResponse, error)
GetUpdates 执行一次消息长轮询。内部超时返回空消息,调用方取消返回错误。
func (*Client) ReceiveMessages ¶ added in v1.2.0
func (c *Client) ReceiveMessages(ctx context.Context, handler func(context.Context, Message) error) error
ReceiveMessages 持续接收消息并按服务端返回顺序交给 handler,直到发生错误或 ctx 结束。
func (*Client) SendText ¶
func (c *Client) SendText(ctx context.Context, request SendTextRequest) (*SendTextResponse, error)
SendText 主动发送或回复一条文本消息。
type GetQRCodeRequest ¶
type GetQRCodeRequest struct {
LocalTokens []string
}
GetQRCodeRequest 配置登录二维码请求。
type GetQRCodeResponse ¶
type GetQRCodeResponse struct {
QRCode string `json:"qrcode"`
QRCodeImageContent string `json:"qrcode_img_content"`
}
GetQRCodeResponse 返回二维码值和用于展示的二维码内容。
func (GetQRCodeResponse) PrintQRCode ¶
func (r GetQRCodeResponse) PrintQRCode() error
PrintQRCode 将二维码输出到标准输出。
func (GetQRCodeResponse) WriteQRCode ¶
func (r GetQRCodeResponse) WriteQRCode(writer io.Writer) error
WriteQRCode 将二维码以适合终端显示的半高字符写入目标 Writer。
type GetQRCodeStatusRequest ¶
GetQRCodeStatusRequest 配置一次二维码状态长轮询。
type GetQRCodeStatusResponse ¶
type GetQRCodeStatusResponse struct {
Status QRCodeStatus `json:"status"`
BotToken string `json:"bot_token,omitempty"`
BotID string `json:"ilink_bot_id,omitempty"`
BaseURL string `json:"baseurl,omitempty"`
UserID string `json:"ilink_user_id,omitempty"`
RedirectHost string `json:"redirect_host,omitempty"`
}
GetQRCodeStatusResponse 返回当前登录状态及确认后的账号凭证。
func (GetQRCodeStatusResponse) RedirectBaseURL ¶
func (r GetQRCodeStatusResponse) RedirectBaseURL() (string, error)
RedirectBaseURL 校验并返回 scaned_but_redirect 状态提供的新轮询地址。
type GetUpdatesRequest ¶
GetUpdatesRequest 配置一次消息长轮询。
type GetUpdatesResponse ¶
type GetUpdatesResponse struct {
Ret *int `json:"ret,omitempty"`
ErrorCode *int `json:"errcode,omitempty"`
ErrorMessage string `json:"errmsg,omitempty"`
Messages []Message `json:"msgs,omitempty"`
Cursor string `json:"get_updates_buf,omitempty"`
LongPollingTimeoutMS int64 `json:"longpolling_timeout_ms,omitempty"`
}
GetUpdatesResponse 返回消息、下次游标和服务端建议的长轮询超时。
func (GetUpdatesResponse) LongPollingTimeout ¶
func (r GetUpdatesResponse) LongPollingTimeout() time.Duration
LongPollingTimeout 返回服务端建议的下一次消息长轮询超时。
func (GetUpdatesResponse) NextCursor ¶
func (r GetUpdatesResponse) NextCursor(current string) string
NextCursor 返回服务端提供的非空游标;空游标时保留当前值。
type Message ¶
type Message struct {
Sequence int64 `json:"seq,omitempty"`
MessageID MessageID `json:"message_id,omitempty"`
FromUserID string `json:"from_user_id,omitempty"`
ToUserID string `json:"to_user_id,omitempty"`
ClientID string `json:"client_id,omitempty"`
CreateTimeMS int64 `json:"create_time_ms,omitempty"`
UpdateTimeMS int64 `json:"update_time_ms,omitempty"`
DeleteTimeMS int64 `json:"delete_time_ms,omitempty"`
SessionID string `json:"session_id,omitempty"`
GroupID string `json:"group_id,omitempty"`
Type MessageType `json:"message_type,omitempty"`
State MessageState `json:"message_state,omitempty"`
Items []MessageItem `json:"item_list,omitempty"`
ContextToken string `json:"context_token,omitempty"`
RunID string `json:"run_id,omitempty"`
}
Message 表示 getUpdates 返回的微信消息。
type MessageID ¶
type MessageID string
MessageID 无损保存微信协议中可能以 JSON 数字或字符串返回的 uint64 ID。
func (*MessageID) UnmarshalJSON ¶
UnmarshalJSON 同时接受 JSON 数字和字符串,避免转换为浮点数造成精度损失。
type MessageItem ¶
type MessageItem struct {
Type MessageItemType `json:"type,omitempty"`
CreateTimeMS int64 `json:"create_time_ms,omitempty"`
UpdateTimeMS int64 `json:"update_time_ms,omitempty"`
Completed bool `json:"is_completed,omitempty"`
MessageID MessageID `json:"msg_id,omitempty"`
Text *TextItem `json:"text_item,omitempty"`
}
MessageItem 表示单个消息内容项。媒体类型当前仅保留类型信息,不执行下载或解码。
type MessageItemType ¶
type MessageItemType int
MessageItemType 表示消息内容类型。
const ( MessageItemTypeNone MessageItemType = iota MessageItemTypeText MessageItemTypeImage MessageItemTypeVoice MessageItemTypeFile MessageItemTypeVideo MessageItemTypeToolCallStart MessageItemType = 11 MessageItemTypeToolCallResult MessageItemType = 12 )
type MessageState ¶
type MessageState int
MessageState 表示消息生成状态。
const ( MessageStateNew MessageState = iota MessageStateGenerating MessageStateFinished )
type MessageType ¶
type MessageType int
MessageType 表示消息发送方类型。
const ( MessageTypeNone MessageType = iota MessageTypeUser MessageTypeBot )
type Option ¶
type Option func(*Client)
func WithBotAgent ¶
WithBotAgent 配置 base_info 中仅用于观测归因的客户端标识。
func WithChannelVersion ¶
WithChannelVersion 覆盖 base_info 和客户端请求头使用的版本号。
func WithClient ¶
WithClient 注入自定义 restx 客户端,主要用于调整传输配置或本地测试。
func WithInsecureHTTP ¶
func WithInsecureHTTP() Option
WithInsecureHTTP 显式允许使用明文 HTTP API 地址,仅应用于可信的开发或测试环境。
func WithLongPollTimeout ¶
WithLongPollTimeout 配置二维码状态和消息查询的单次长轮询超时。
type QRCodeStatus ¶
type QRCodeStatus string
QRCodeStatus 表示二维码登录状态。
const ( QRCodeStatusWait QRCodeStatus = "wait" QRCodeStatusScanned QRCodeStatus = "scaned" QRCodeStatusConfirmed QRCodeStatus = "confirmed" QRCodeStatusExpired QRCodeStatus = "expired" QRCodeStatusNeedVerifyCode QRCodeStatus = "need_verifycode" QRCodeStatusVerifyCodeBlocked QRCodeStatus = "verify_code_blocked" QRCodeStatusScannedRedirect QRCodeStatus = "scaned_but_redirect" QRCodeStatusBoundRedirect QRCodeStatus = "binded_redirect" )
type SendTextRequest ¶
SendTextRequest 配置一条主动发送或回复的文本消息。
type SendTextResponse ¶
SendTextResponse 返回本地 Client ID 和服务端消息 ID。