@starim-io/bot-sdk 0.1.4

package/dist/index.d.cts

@@ -0,0 +1,727 @@
+import { Server } from 'node:http';
+
+/**
+ * 与 bot-service BotUpdateDispatcher / Webhook 投递载荷对齐的 Update 类型。
+ * @see server/services/bot/src/services/BotUpdateDispatcher.js
+ */
+type UpdateType = 'message' | 'photo' | 'document' | 'video' | 'audio' | 'location' | 'edited_message' | 'message_deleted' | 'message_read' | 'message_delivered' | 'callback_query' | 'inline_query' | 'friend_request' | 'my_chat_member' | 'chat_member' | 'chat_join_request';
+interface StarIMUser {
+    id: string;
+    username?: string;
+    first_name?: string;
+    is_bot: boolean;
+}
+interface Chat {
+    id: string;
+    type: 'private' | 'group';
+    title?: string;
+}
+interface MessageFile {
+    file_id: string;
+    file_name?: string;
+    mime_type?: string;
+    file_size?: number;
+    url?: string;
+    thumbnail_url?: string;
+}
+interface MessageLocation {
+    latitude: number;
+    longitude: number;
+    name?: string;
+    address?: string;
+}
+interface InlineKeyboardButton {
+    text: string;
+    callback_data?: string;
+    url?: string;
+}
+interface KeyboardButton {
+    text: string;
+}
+/** Inline 按钮键盘 */
+interface ReplyMarkupInline {
+    inline_keyboard: InlineKeyboardButton[][];
+}
+/** 底部回复键盘（ReplyKeyboard） */
+interface ReplyMarkupReplyKeyboard {
+    keyboard: (string | KeyboardButton)[][];
+    resize_keyboard?: boolean;
+    one_time_keyboard?: boolean;
+    is_persistent?: boolean;
+    input_field_placeholder?: string;
+}
+interface ReplyMarkupRemove {
+    remove_keyboard: true;
+    selective?: boolean;
+}
+type ReplyMarkup = ReplyMarkupInline | ReplyMarkupReplyKeyboard | ReplyMarkupRemove;
+interface BotCommand {
+    command: string;
+    description: string;
+}
+interface SetMyCommandsParams {
+    commands: BotCommand[];
+    scope?: string | {
+        type: string;
+    };
+    language_code?: string;
+}
+interface GetMyCommandsParams {
+    scope?: string;
+    language_code?: string;
+}
+interface DeleteMyCommandsParams {
+    scope?: string | {
+        type: string;
+    };
+    language_code?: string;
+}
+/** Webhook / Update 中的 message 对象（字段随 type 增减） */
+interface WebhookMessage {
+    message_id: string;
+    from?: StarIMUser;
+    chat: Chat;
+    text?: string;
+    date: number;
+    file?: MessageFile;
+    location?: MessageLocation;
+    reply_markup?: ReplyMarkup;
+    metadata?: Record<string, unknown>;
+}
+interface CallbackQuery {
+    id: string;
+    from: StarIMUser;
+    message?: WebhookMessage;
+    data: string;
+    chat_instance?: string;
+    created_at?: string | number;
+}
+/** Inline Mode 查询载荷 */
+interface InlineQuery {
+    id: string;
+    from: StarIMUser;
+    query: string;
+    offset: string;
+    chat_type?: 'private' | 'group' | string;
+}
+/** 用户向机器人发起好友申请（Bot friend_request_mode = manual） */
+interface FriendRequestUpdate {
+    /** 对应 Friendship._id */
+    id: string;
+    from: StarIMUser;
+    request_message: string;
+    source: string;
+    date: number;
+}
+/** 群成员状态片段（status 为字符串枚举） */
+interface ChatMember {
+    user: StarIMUser;
+    status: string;
+}
+/** my_chat_member / chat_member 载荷 */
+interface ChatMemberUpdated {
+    chat: Chat;
+    from: StarIMUser;
+    date: number;
+    old_chat_member: ChatMember;
+    new_chat_member: ChatMember;
+}
+/** 入群申请（管理员机器人可收） */
+interface ChatJoinRequestUpdate {
+    chat: Chat;
+    from: StarIMUser;
+    user_chat_id: string;
+    date: number;
+    bio?: string;
+}
+interface AnswerFriendRequestParams {
+    friendship_id: string;
+    action: 'accept' | 'reject';
+}
+type FriendRequestMode = 'auto_accept' | 'auto_reject' | 'manual';
+interface SetMyFriendRequestModeParams {
+    friend_request_mode: FriendRequestMode;
+}
+/** GET /bots/getFriendRequests 单条（与测试机器人后管列表字段对齐） */
+interface BotFriendRequestListItem {
+    id: string;
+    update_id: string;
+    ts: string;
+    fromUserId: string;
+    fromUsername: string;
+    requestMessage: string;
+    source: string;
+    status: 'pending' | 'accepted' | 'rejected';
+    date?: number;
+}
+interface Update {
+    update_id: string;
+    type: UpdateType;
+    bot_id: string;
+    message?: WebhookMessage;
+    callback_query?: CallbackQuery;
+    inline_query?: InlineQuery;
+    friend_request?: FriendRequestUpdate;
+    my_chat_member?: ChatMemberUpdated;
+    chat_member?: ChatMemberUpdated;
+    chat_join_request?: ChatJoinRequestUpdate;
+    date?: number;
+    /** polling 模式（getUpdates）专属：单调递增序号，用于实现 offset ack 语义 */
+    update_seq?: number;
+}
+/** getUpdates 入参 */
+interface GetUpdatesParams {
+    /**
+     * 拉取 update_seq >= offset 的条目。
+     * 推荐用「上一批最后一条 update_seq + 1」作为下次 offset，等价 ack。
+     */
+    offset?: number;
+    /** 1..100，默认 100 */
+    limit?: number;
+    /** long-poll 秒数，0 立即返回，最大 50；默认 0 */
+    timeout?: number;
+    /** 仅返回 type 命中的；缺省 = 全部 */
+    allowed_updates?: UpdateType[] | string[];
+}
+interface GetUpdatesResult {
+    updates: Update[];
+}
+interface SetWebhookParams {
+    url: string;
+    secret_token?: string;
+    allowed_updates?: string[];
+    allowed_ips?: string[];
+}
+interface SendMessageParams {
+    chat_id: string;
+    text: string;
+    reply_markup?: ReplyMarkup;
+}
+interface SendMediaParams {
+    chat_id: string;
+    file_id: string;
+    caption?: string;
+    /** 时长（秒），语音/视频等；不传则 App 端可能显示为 0″ */
+    duration?: number;
+    /** 与 Bot API `length` 同义（视频笔记时长） */
+    length?: number;
+    /** 视频等；与网关 sendVideo 一致 */
+    width?: number;
+    height?: number;
+    performer?: string;
+    title?: string;
+    /** 网关字段 `thumbnail_url` */
+    thumbnail_url?: string;
+}
+interface SendLocationParams {
+    chat_id: string;
+    latitude: number;
+    longitude: number;
+    name?: string;
+    address?: string;
+}
+interface SendVenueParams {
+    chat_id: string;
+    latitude: number;
+    longitude: number;
+    title: string;
+    address?: string;
+    reply_markup?: ReplyMarkup;
+}
+interface SendDiceParams {
+    chat_id: string;
+    emoji?: string;
+    reply_markup?: ReplyMarkup;
+}
+interface SendPollParams {
+    chat_id: string;
+    question: string;
+    options: string[];
+    is_anonymous?: boolean;
+    type?: 'regular' | 'quiz';
+    correct_option_id?: number;
+    reply_markup?: ReplyMarkup;
+}
+interface SendContactParams {
+    chat_id: string;
+    phone_number: string;
+    first_name: string;
+    last_name?: string;
+    reply_markup?: ReplyMarkup;
+}
+/** sendMediaGroup：与网关约定 type = photo|video|document|audio */
+interface SendMediaGroupItem {
+    type: 'photo' | 'image' | 'video' | 'document' | 'audio';
+    /** 兼容字段名（与 file_id 二选一） */
+    media?: string;
+    file_id?: string;
+    caption?: string;
+}
+interface SendMediaGroupParams {
+    chat_id: string;
+    media: SendMediaGroupItem[];
+    reply_markup?: ReplyMarkup;
+}
+interface EditMessageParams {
+    message_id: string;
+    text?: string;
+    content?: string;
+    reply_markup?: ReplyMarkup | null;
+}
+interface EditMessageReplyMarkupParams {
+    message_id: string;
+    reply_markup?: ReplyMarkup | null;
+}
+interface AnswerCallbackQueryParams {
+    callback_query_id: string;
+    text?: string;
+    show_alert?: boolean;
+    url?: string;
+    cache_time?: number;
+}
+/** answerInlineQuery：首期仅支持 article + InputTextMessageContent（与平台校验一致） */
+interface AnswerInlineQueryParams {
+    inline_query_id: string;
+    results: Record<string, unknown>[];
+    cache_time?: number;
+    is_personal?: boolean;
+    next_offset?: string;
+}
+/** 群治理：chat_id 为群会话 Mongo _id（与 sendMessage 一致） */
+interface KickChatMemberParams {
+    chat_id: string;
+    user_id: string;
+}
+interface BanChatMemberParams extends KickChatMemberParams {
+    reason?: string;
+}
+interface DeleteMessageParams {
+    message_id: string;
+}
+interface IssueUploadCredentialsParams {
+    fileName: string;
+    fileSize: number;
+    fileType?: string;
+    checksum?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CompleteUploadParams {
+    key: string;
+    fileName: string;
+    fileSize: number;
+    fileType?: string;
+    checksum?: string;
+    category?: string;
+    isPublic?: boolean;
+}
+/** file.getS3Credentials 返回（与 s3UploadService.generateUploadCredentials 对齐） */
+interface UploadCredentials {
+    uploadUrl: string;
+    method: string;
+    key: string;
+    bucket: string;
+    region: string;
+    expiresIn: number;
+    maxSize: number;
+    contentType: string;
+    objectUrl: string;
+}
+/** complete 登记返回 */
+interface CompletedUpload {
+    id: string;
+    url: string;
+    objectUrl?: string;
+    key?: string;
+    fileName?: string;
+    originalName?: string;
+    size?: number;
+    mimeType?: string;
+}
+type LoggerFn = (level: 'debug' | 'info' | 'warn' | 'error', msg: string, meta?: object) => void;
+interface StarIMBotClientOptions {
+    token: string;
+    /** 含 `/api/v1` 前缀的网关根，如 `https://your-gateway.example/api/v1` */
+    baseUrl?: string;
+    timeoutMs?: number;
+    /** 为 true 时通过 logger 输出请求元信息（绝不打印 token） */
+    debug?: boolean;
+    logger?: Pick<Console, 'debug' | 'info' | 'warn' | 'error'>;
+}
+interface StarIMBotOptions extends StarIMBotClientOptions {
+    /** 与 setWebhook 时配置的 secret_token 一致，用于校验 X-StarIM-Signature */
+    secretToken: string;
+    /** 去重缓存大小，默认 1024 */
+    dedupeSize?: number;
+}
+
+declare class StarIMBotClient {
+    readonly token: string;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly debug;
+    /** 暴露给上层（如 StarIMBot polling 链路）以记录非致命错误 */
+    readonly logger: Pick<Console, 'debug' | 'info' | 'warn' | 'error'>;
+    readonly files: {
+        issueUploadCredentials: (p: IssueUploadCredentialsParams) => Promise<UploadCredentials>;
+        completeUpload: (p: CompleteUploadParams) => Promise<CompletedUpload>;
+    };
+    constructor(opts: StarIMBotClientOptions);
+    private log;
+    private request;
+    /** GET /bots/me */
+    getMe(): Promise<Record<string, unknown>>;
+    /** GET /bots/getChat?chat_id= */
+    getChat(chat_id: string): Promise<Record<string, unknown>>;
+    getChatMember(chat_id: string, user_id: string): Promise<Record<string, unknown>>;
+    getChatMemberCount(chat_id: string): Promise<Record<string, unknown>>;
+    getChatAdministrators(chat_id: string): Promise<Record<string, unknown>>;
+    setChatTitle(chat_id: string, title: string): Promise<unknown>;
+    setChatDescription(chat_id: string, description: string): Promise<unknown>;
+    setChatPhoto(chat_id: string, photo: string): Promise<unknown>;
+    pinChatMessage(body: Record<string, unknown>): Promise<unknown>;
+    unpinChatMessage(body: Record<string, unknown>): Promise<unknown>;
+    unpinAllChatMessages(chat_id: string): Promise<unknown>;
+    forwardMessage(body: Record<string, unknown>): Promise<unknown>;
+    copyMessage(body: Record<string, unknown>): Promise<unknown>;
+    sendChatAction(chat_id: string, action: string): Promise<unknown>;
+    getFile(file_id: string): Promise<Record<string, unknown>>;
+    /** POST /bots/sendMessage */
+    sendMessage(params: SendMessageParams): Promise<unknown>;
+    /** POST /bots/setMyCommands */
+    setMyCommands(params: SetMyCommandsParams): Promise<unknown>;
+    /** GET /bots/getMyCommands */
+    getMyCommands(params?: GetMyCommandsParams): Promise<{
+        commands: BotCommand[];
+    }>;
+    /** POST /bots/deleteMyCommands */
+    deleteMyCommands(params?: DeleteMyCommandsParams): Promise<unknown>;
+    /** POST /bots/setMyShortDescription · 设置短描述（≤120 字） */
+    setMyShortDescription(short_description: string): Promise<{
+        short_description: string;
+    }>;
+    /** GET /bots/getMyShortDescription · 获取短描述 */
+    getMyShortDescription(): Promise<{
+        short_description: string;
+    }>;
+    /** POST /bots/setMyDescription · 设置 Bot 主页大段「关于」文本（≤512 字） */
+    setMyDescription(description: string): Promise<{
+        description: string;
+    }>;
+    /** GET /bots/getMyDescription · 获取 Bot 主页大段「关于」文本 */
+    getMyDescription(): Promise<{
+        description: string;
+    }>;
+    setWebhook(params: SetWebhookParams): Promise<unknown>;
+    deleteWebhook(): Promise<unknown>;
+    /** GET /bots/getWebhookInfo */
+    getWebhookInfo(): Promise<Record<string, unknown>>;
+    /**
+     * POST /bots/getUpdates · 长轮询拉取 polling 模式 update。
+     *
+     * - 调本接口前请确保已 `deleteWebhook`，否则平台返回 409。
+     * - HTTP 客户端的超时会按 `timeout + 5s` 自动放宽，避免比服务端先断开。
+     *
+     * @example
+     * ```ts
+     * let offset = 0;
+     * while (true) {
+     *   const { updates } = await client.getUpdates({ timeout: 30, offset });
+     *   for (const u of updates) {
+     *     console.log(u);
+     *     if (typeof u.update_seq === 'number') offset = u.update_seq + 1;
+     *   }
+     * }
+     * ```
+     */
+    getUpdates(params?: GetUpdatesParams): Promise<GetUpdatesResult>;
+    sendPhoto(params: SendMediaParams): Promise<unknown>;
+    sendDocument(params: SendMediaParams): Promise<unknown>;
+    sendVideo(params: SendMediaParams): Promise<unknown>;
+    sendAudio(params: SendMediaParams): Promise<unknown>;
+    sendVoice(params: SendMediaParams): Promise<unknown>;
+    sendVideoNote(params: SendMediaParams): Promise<unknown>;
+    sendAnimation(params: SendMediaParams): Promise<unknown>;
+    sendSticker(params: SendMediaParams): Promise<unknown>;
+    sendDice(params: SendDiceParams): Promise<unknown>;
+    sendPoll(params: SendPollParams): Promise<unknown>;
+    sendContact(params: SendContactParams): Promise<unknown>;
+    sendMediaGroup(params: SendMediaGroupParams): Promise<unknown>;
+    private buildSendMediaBody;
+    private buildSendVideoNoteBody;
+    sendLocation(params: SendLocationParams): Promise<unknown>;
+    sendVenue(params: SendVenueParams): Promise<unknown>;
+    editMessage(params: EditMessageParams): Promise<unknown>;
+    editMessageReplyMarkup(params: EditMessageReplyMarkupParams): Promise<unknown>;
+    answerCallbackQuery(params: AnswerCallbackQueryParams): Promise<unknown>;
+    answerInlineQuery(params: AnswerInlineQueryParams): Promise<unknown>;
+    /** POST /bots/answerFriendRequest · manual 模式下处理用户发起的好友申请 */
+    answerFriendRequest(params: AnswerFriendRequestParams): Promise<unknown>;
+    /** POST /bots/setMyFriendRequestMode · 配置当前机器人好友申请处理策略 */
+    setMyFriendRequestMode(params: SetMyFriendRequestModeParams): Promise<{
+        friend_request_mode: string;
+    }>;
+    /** GET /bots/getMyFriendRequestMode · 获取当前机器人好友申请处理策略 */
+    getMyFriendRequestMode(): Promise<{
+        friend_request_mode: string;
+    }>;
+    /** GET /bots/getFriendRequests · 待处理好友申请（数据库 Friendship） */
+    getFriendRequests(): Promise<{
+        friend_requests: BotFriendRequestListItem[];
+    }>;
+    kickChatMember(params: KickChatMemberParams): Promise<unknown>;
+    banChatMember(params: BanChatMemberParams): Promise<unknown>;
+    unbanChatMember(params: KickChatMemberParams): Promise<unknown>;
+    deleteMessage(params: DeleteMessageParams): Promise<unknown>;
+    issueUploadCredentials(p: IssueUploadCredentialsParams): Promise<UploadCredentials>;
+    completeUpload(p: CompleteUploadParams): Promise<CompletedUpload>;
+    /**
+     * 校验 Token（公开接口，不强制带 Bearer，仅 body.token）。
+     */
+    verifyToken(): Promise<{
+        bot?: Record<string, unknown>;
+    }>;
+    /** 本地路径 → 上传 S3 → sendPhoto */
+    sendPhotoFromFile(chatId: string, filePath: string, options?: {
+        caption?: string;
+        fileName?: string;
+        fileType?: string;
+    }): Promise<unknown>;
+    /** 本地路径 → 上传 S3 → sendDocument */
+    sendDocumentFromFile(chatId: string, filePath: string, options?: {
+        caption?: string;
+        fileName?: string;
+        fileType?: string;
+    }): Promise<unknown>;
+}
+
+/** V2 时间戳容忍窗口（秒）。客户端时钟与服务端偏差超过此值则拒收，防 replay。 */
+declare const DEFAULT_TIMESTAMP_TOLERANCE_SEC = 300;
+/**
+ * V2 签名：HMAC-SHA256(`${timestamp}.${body}`)，hex 小写。
+ *
+ * timestamp 为 unix 秒（与服务端 `X-StarIM-Timestamp` 头一致）。
+ */
+declare function computeWebhookSignatureV2(secret: string, timestampSec: number | string, rawBody: Buffer | string): string;
+interface VerifyWebhookOptions {
+    /** V2 时间戳容忍窗口（秒），默认 300 */
+    timestampToleranceSec?: number;
+    /** 注入时钟，便于测试 */
+    nowSec?: () => number;
+}
+/**
+ * 校验 webhook V2 签名（须同时提供 X-StarIM-Signature-V2 与 X-StarIM-Timestamp）。
+ *
+ * @throws {StarIMSignatureError} 校验失败
+ */
+declare function verifyWebhookSignature(secret: string, rawBody: Buffer | string, signatureHeaderV2: string | undefined, timestampHeader: string | undefined, opts?: VerifyWebhookOptions): void;
+interface WebhookRequest {
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+    /** express.raw / body-parser raw 解析后的 Buffer */
+    body?: unknown;
+    /** 可选：在 json 解析前由中间件挂载的原始字节 */
+    rawBody?: Buffer;
+}
+interface WebhookResponse {
+    statusCode?: number;
+    setHeader?(name: string, value: string | number | readonly string[]): unknown;
+    end(chunk?: string | Uint8Array): void;
+}
+interface DedupeStore {
+    /** 若已处理过该 update_id 返回 true */
+    has(updateId: string): boolean;
+    add(updateId: string): void;
+}
+/** 简单 LRU：超过容量时删除最旧条目 */
+declare class LruDedupe implements DedupeStore {
+    private readonly maxSize;
+    private readonly order;
+    private readonly set;
+    constructor(maxSize: number);
+    has(updateId: string): boolean;
+    add(updateId: string): void;
+}
+interface ProcessWebhookOptions {
+    secretToken: string;
+    dedupe?: DedupeStore;
+    /** 透传给 verifyWebhookSignature */
+    verify?: VerifyWebhookOptions;
+}
+interface ProcessWebhookResult {
+    update: Update;
+    duplicate: boolean;
+}
+/**
+ * 校验签名、解析 Update、可选幂等去重。
+ * duplicate 为 true 时表示 update_id 已见过，业务层可选择跳过重复投递。
+ */
+declare function processWebhook(req: WebhookRequest, opts: ProcessWebhookOptions): ProcessWebhookResult;
+interface WebhookMiddlewareOptions extends ProcessWebhookOptions {
+    onUpdate: (update: Update, ctx: {
+        rawBody: Buffer;
+        duplicate: boolean;
+    }) => void | Promise<void>;
+    /** 重复 update_id 时仍调用 onUpdate，默认 false */
+    invokeOnDuplicate?: boolean;
+}
+/**
+ * Connect/Express 风格中间件：请务必在 JSON 解析前保留 raw body。
+ */
+declare function webhookMiddleware(opts: WebhookMiddlewareOptions): (req: WebhookRequest, res: WebhookResponse, next?: (err?: unknown) => void) => Promise<void>;
+
+type BotContext = {
+    update: Update;
+    /** 原始 POST body（与签名校验一致的字节） */
+    rawBody: Buffer;
+    /** 平台重试导致的重复 update_id */
+    duplicate: boolean;
+    client: StarIMBotClient;
+    /** 当前载荷中的 message（编辑/删除场景字段可能不全） */
+    message: WebhookMessage;
+    chat: WebhookMessage['chat'];
+    /** InlineKeyboard 点击事件，仅 callback_query Update 存在 */
+    callbackQuery?: CallbackQuery;
+    /** Inline Mode 查询，仅 inline_query Update 存在 */
+    inlineQuery?: InlineQuery;
+    /** 用户发起的好友申请，仅 friend_request Update 存在 */
+    friendRequest?: FriendRequestUpdate;
+    /** 机器人自身被加入/移出/状态变化，仅 my_chat_member Update 存在 */
+    myChatMember?: ChatMemberUpdated;
+    /** 群内其它成员状态变化（机器人需是管理员），仅 chat_member Update 存在 */
+    chatMember?: ChatMemberUpdated;
+    /** 群入群申请，仅 chat_join_request Update 存在 */
+    chatJoinRequest?: ChatJoinRequestUpdate;
+    /** 快捷回复文本到当前会话 */
+    reply: (text: string, options?: {
+        reply_markup?: ReplyMarkup;
+    }) => ReturnType<StarIMBotClient['sendMessage']>;
+    /** 快捷回应当前 callback_query */
+    answerCallback: (params?: Omit<AnswerCallbackQueryParams, 'callback_query_id'>) => ReturnType<StarIMBotClient['answerCallbackQuery']>;
+    /** 快捷应答当前 inline_query */
+    answerInlineQuery: (params: Omit<AnswerInlineQueryParams, 'inline_query_id'>) => ReturnType<StarIMBotClient['answerInlineQuery']>;
+};
+type Handler = (ctx: BotContext) => void | Promise<void>;
+declare class StarIMBot {
+    readonly client: StarIMBotClient;
+    private readonly secretToken;
+    private readonly dedupe;
+    private readonly handlers;
+    private readonly commands;
+    private pollingActive;
+    private pollingOffset;
+    constructor(opts: StarIMBotOptions);
+    on(type: UpdateType | '*', handler: Handler): this;
+    /**
+     * 仅匹配文本消息中以 `/name` 开头的命令（大小写不敏感）。
+     */
+    command(name: string, handler: Handler): this;
+    private dispatch;
+    /**
+     * Express / Connect 中间件：先挂载 express.raw（例如 type: application/json），再使用本回调。
+     */
+    webhookCallback(): (req: WebhookRequest, res: WebhookResponse, next?: (err?: unknown) => void) => Promise<void>;
+    /**
+     * 长轮询模式：循环调用 getUpdates，把 update 喂给与 Webhook 相同的 dispatch 链路。
+     *
+     * 适用场景：
+     *  - 没有公网 IP / HTTPS 证书的本机开发；
+     *  - CI / 测试环境快速接入。
+     *
+     * 使用前请先 `await client.deleteWebhook()`，否则平台返回 409。
+     * 内部维护 offset、自动捕获错误并指数退避重试；调用 `stopPolling()` 优雅退出。
+     *
+     * @example
+     * ```ts
+     * await bot.client.deleteWebhook();
+     * await bot.startPolling({ timeout: 30 });
+     * ```
+     */
+    startPolling(options?: {
+        timeout?: number;
+        limit?: number;
+        allowedUpdates?: string[];
+        /** 平台返回错误时的最大退避秒数，默认 30 */
+        maxBackoffSec?: number;
+    }): Promise<void>;
+    /** 停止 startPolling 的循环（不会立刻打断当前 long-poll，等当次 RPC 返回后退出） */
+    stopPolling(): void;
+    /**
+     * 内置 HTTP 服务，便于快速起 Webhook（生产环境建议使用反向代理 + TLS）。
+     */
+    start(options: {
+        port: number;
+        host?: string;
+        path?: string;
+    }): Promise<Server>;
+    private createContext;
+}
+
+/**
+ * Bot API 或 Webhook 处理中的可恢复错误。
+ */
+declare class StarIMApiError extends Error {
+    readonly code?: string | number;
+    readonly statusCode: number;
+    readonly responseBody?: unknown;
+    constructor(opts: {
+        message: string;
+        statusCode: number;
+        code?: string | number;
+        responseBody?: unknown;
+    });
+}
+/**
+ * Webhook 签名校验失败。
+ */
+declare class StarIMSignatureError extends Error {
+    constructor(message?: string);
+}
+
+/** 从本地路径读取并上传，返回登记后的 file id */
+declare function uploadFileFromPath(client: StarIMBotClient, filePath: string, options?: {
+    fileName?: string;
+    fileType?: string;
+}): Promise<CompletedUpload>;
+declare function uploadFromUrl(client: StarIMBotClient, sourceUrl: string, options?: {
+    fileName?: string;
+    fileType?: string;
+}): Promise<CompletedUpload>;
+declare function sendPhotoFromPath(client: StarIMBotClient, chatId: string, filePath: string, options?: {
+    caption?: string;
+    fileName?: string;
+    fileType?: string;
+}): Promise<unknown>;
+declare function sendDocumentFromPath(client: StarIMBotClient, chatId: string, filePath: string, options?: {
+    caption?: string;
+    fileName?: string;
+    fileType?: string;
+}): Promise<unknown>;
+/**
+ * Buffer 上传后发送图片。
+ */
+declare function sendPhotoFromBuffer(client: StarIMBotClient, chatId: string, buffer: Buffer, options?: {
+    caption?: string;
+    fileName?: string;
+    fileType?: string;
+}): Promise<unknown>;
+/**
+ * 远程 URL 下载后发送图片。
+ */
+declare function sendPhotoFromUrl(client: StarIMBotClient, chatId: string, sourceUrl: string, options?: {
+    caption?: string;
+    fileName?: string;
+    fileType?: string;
+}): Promise<unknown>;
+/**
+ * 远程 URL 下载后发送视频（先上传再 sendVideo）。
+ */
+declare function sendVideoFromUrl(client: StarIMBotClient, chatId: string, sourceUrl: string, options?: {
+    caption?: string;
+    fileName?: string;
+    fileType?: string;
+    duration?: number;
+    width?: number;
+    height?: number;
+}): Promise<unknown>;
+
+export { type AnswerCallbackQueryParams, type AnswerFriendRequestParams, type AnswerInlineQueryParams, type BanChatMemberParams, type BotCommand, type BotContext, type BotFriendRequestListItem, type CallbackQuery, type Chat, type CompleteUploadParams, type CompletedUpload, DEFAULT_TIMESTAMP_TOLERANCE_SEC, type DedupeStore, type DeleteMessageParams, type DeleteMyCommandsParams, type EditMessageParams, type EditMessageReplyMarkupParams, type FriendRequestUpdate, type GetMyCommandsParams, type InlineKeyboardButton, type InlineQuery, type IssueUploadCredentialsParams, type KeyboardButton, type KickChatMemberParams, type LoggerFn, LruDedupe, type MessageFile, type MessageLocation, type ProcessWebhookOptions, type ProcessWebhookResult, type ReplyMarkup, type ReplyMarkupInline, type ReplyMarkupRemove, type ReplyMarkupReplyKeyboard, type SendContactParams, type SendDiceParams, type SendLocationParams, type SendMediaGroupItem, type SendMediaGroupParams, type SendMediaParams, type SendMessageParams, type SendPollParams, type SendVenueParams, type SetMyCommandsParams, type SetWebhookParams, StarIMApiError, StarIMBot, StarIMBotClient, type StarIMBotClientOptions, type StarIMBotOptions, StarIMSignatureError, type StarIMUser, type Update, type UpdateType, type UploadCredentials, type VerifyWebhookOptions, type WebhookMessage, type WebhookMiddlewareOptions, type WebhookRequest, type WebhookResponse, computeWebhookSignatureV2, processWebhook, sendDocumentFromPath, sendPhotoFromBuffer, sendPhotoFromPath, sendPhotoFromUrl, sendVideoFromUrl, uploadFileFromPath, uploadFromUrl, verifyWebhookSignature, webhookMiddleware };