botmux 2.26.0 → 2.27.1

package/dist/setup/lark-scopes.json

@@ -0,0 +1,301 @@
+{
+  "scopes": {
+    "tenant": [
+      "ai:llpp:task_execute",
+      "application:application:self_manage",
+      "application:bot.menu:write",
+      "audio_video_ai:meeting_assistance",
+      "auth:user_access_token:read",
+      "board:whiteboard:node:create",
+      "board:whiteboard:node:delete",
+      "board:whiteboard:node:read",
+      "board:whiteboard:node:update",
+      "calendar:calendar.acl:create",
+      "calendar:calendar.acl:delete",
+      "calendar:calendar.acl:read",
+      "calendar:calendar.event:create",
+      "calendar:calendar.event:delete",
+      "calendar:calendar.event:read",
+      "calendar:calendar.event:reply",
+      "calendar:calendar.event:update",
+      "calendar:calendar.free_busy:read",
+      "calendar:calendar:create",
+      "calendar:calendar:delete",
+      "calendar:calendar:read",
+      "calendar:calendar:subscribe",
+      "calendar:calendar:update",
+      "cardkit:card:read",
+      "cardkit:card:write",
+      "comment_sdk:comment_sdk",
+      "component:url_preview",
+      "contact:contact.base:readonly",
+      "contact:user.base:readonly",
+      "contact:user.email:readonly",
+      "contact:user.employee_id:readonly",
+      "contact:user.id:readonly",
+      "directory:employee.base.external_id:read",
+      "directory:employee.work.job_number:read",
+      "directory:job_title.status:read",
+      "docs:document.comment:create",
+      "docs:document.comment:delete",
+      "docs:document.comment:read",
+      "docs:document.comment:update",
+      "docs:document.comment:write_only",
+      "docs:document.content:read",
+      "docs:document.media:download",
+      "docs:document.media:upload",
+      "docs:document.subscription",
+      "docs:document.subscription:read",
+      "docs:document:copy",
+      "docs:document:export",
+      "docs:document:import",
+      "docs:event.document_deleted:read",
+      "docs:event.document_edited:read",
+      "docs:event.document_opened:read",
+      "docs:event:subscribe",
+      "docs:permission.member:auth",
+      "docs:permission.member:create",
+      "docs:permission.member:delete",
+      "docs:permission.member:retrieve",
+      "docs:permission.member:transfer",
+      "docs:permission.member:update",
+      "docs:permission.setting:read",
+      "docs:permission.setting:readonly",
+      "docs:permission.setting:write_only",
+      "docs_tool:docs_tool",
+      "document_ai:document:chunking",
+      "document_ai:kie:llm",
+      "docx:document.block:convert",
+      "docx:document:create",
+      "docx:document:readonly",
+      "docx:document:write_only",
+      "drive:drive.metadata:readonly",
+      "drive:drive.search:readonly",
+      "drive:drive:version",
+      "drive:drive:version:readonly",
+      "drive:file.like:readonly",
+      "drive:file.meta.sec_label.read_only",
+      "drive:file:download",
+      "drive:file:favorite",
+      "drive:file:favorite:readonly",
+      "drive:file:upload",
+      "drive:file:view_record:readonly",
+      "event:failed_event:readonly",
+      "event:ip_list",
+      "im:app_feed_card:write",
+      "im:chat.access_event.bot_p2p_chat:read",
+      "im:chat.announcement:read",
+      "im:chat.announcement:write_only",
+      "im:chat.chat_pins:read",
+      "im:chat.chat_pins:write_only",
+      "im:chat.collab_plugins:read",
+      "im:chat.collab_plugins:write_only",
+      "im:chat.managers:write_only",
+      "im:chat.members:bot_access",
+      "im:chat.members:read",
+      "im:chat.members:write_only",
+      "im:chat.menu_tree:read",
+      "im:chat.menu_tree:write_only",
+      "im:chat.moderation:read",
+      "im:chat.tabs:read",
+      "im:chat.tabs:write_only",
+      "im:chat.top_notice:write_only",
+      "im:chat.widgets:read",
+      "im:chat.widgets:write_only",
+      "im:chat:create",
+      "im:chat:delete",
+      "im:chat:moderation:write_only",
+      "im:chat:operate_as_owner",
+      "im:chat:read",
+      "im:chat:update",
+      "im:message",
+      "im:message.group_at_msg.include_bot:readonly",
+      "im:message.group_at_msg:readonly",
+      "im:message.group_msg",
+      "im:message.p2p_msg:readonly",
+      "im:message.pins:read",
+      "im:message.pins:write_only",
+      "im:message.reactions:read",
+      "im:message.reactions:write_only",
+      "im:message:readonly",
+      "im:message:recall",
+      "im:message:send_as_bot",
+      "im:message:send_multi_depts",
+      "im:message:send_multi_users",
+      "im:message:send_sys_msg",
+      "im:message:update",
+      "im:resource",
+      "im:url_preview.update",
+      "im:user_agent:read",
+      "optical_char_recognition:image",
+      "sheets:spreadsheet.meta:read",
+      "sheets:spreadsheet.meta:write_only",
+      "sheets:spreadsheet:create",
+      "sheets:spreadsheet:read",
+      "sheets:spreadsheet:write_only",
+      "slides:presentation:create",
+      "slides:presentation:read",
+      "slides:presentation:update",
+      "slides:presentation:write_only",
+      "space:document.event:read",
+      "space:document:create",
+      "space:document:delete",
+      "space:document:move",
+      "space:document:retrieve",
+      "space:document:shortcut",
+      "space:folder:create",
+      "speech_to_text:speech",
+      "task:task:read",
+      "task:task:write",
+      "task:tasklist:read",
+      "task:tasklist:write",
+      "translation:text",
+      "wiki:member:create",
+      "wiki:member:retrieve",
+      "wiki:member:update",
+      "wiki:node:copy",
+      "wiki:node:create",
+      "wiki:node:move",
+      "wiki:node:read",
+      "wiki:node:retrieve",
+      "wiki:node:update",
+      "wiki:setting:read",
+      "wiki:setting:write_only",
+      "wiki:space:read",
+      "wiki:space:retrieve",
+      "wiki:space:write_only",
+      "wiki:wiki:readonly"
+    ],
+    "user": [
+      "board:whiteboard:node:create",
+      "board:whiteboard:node:delete",
+      "board:whiteboard:node:read",
+      "board:whiteboard:node:update",
+      "calendar:calendar.acl:create",
+      "calendar:calendar.acl:delete",
+      "calendar:calendar.acl:read",
+      "calendar:calendar.event:create",
+      "calendar:calendar.event:delete",
+      "calendar:calendar.event:read",
+      "calendar:calendar.event:reply",
+      "calendar:calendar.event:update",
+      "calendar:calendar.free_busy:read",
+      "calendar:calendar:create",
+      "calendar:calendar:delete",
+      "calendar:calendar:read",
+      "calendar:calendar:subscribe",
+      "calendar:calendar:update",
+      "comment_sdk:comment_sdk",
+      "contact:contact.base:readonly",
+      "contact:user.employee_id:readonly",
+      "docs:component",
+      "docs:document.comment:create",
+      "docs:document.comment:read",
+      "docs:document.comment:update",
+      "docs:document.comment:write_only",
+      "docs:document.content:read",
+      "docs:document.media:download",
+      "docs:document.media:upload",
+      "docs:document.subscription",
+      "docs:document.subscription:read",
+      "docs:document:copy",
+      "docs:document:export",
+      "docs:document:import",
+      "docs:event.document_deleted:read",
+      "docs:event.document_edited:read",
+      "docs:event.document_opened:read",
+      "docs:event:subscribe",
+      "docs:permission.member:apply",
+      "docs:permission.member:auth",
+      "docs:permission.member:create",
+      "docs:permission.member:delete",
+      "docs:permission.member:retrieve",
+      "docs:permission.member:transfer",
+      "docs:permission.member:update",
+      "docs:permission.setting:read",
+      "docs:permission.setting:readonly",
+      "docs:permission.setting:write_only",
+      "docs_tool:docs_tool",
+      "docx:document.block:convert",
+      "docx:document:create",
+      "docx:document:readonly",
+      "docx:document:write_only",
+      "drive:drive.metadata:readonly",
+      "drive:drive.search:readonly",
+      "drive:drive:version",
+      "drive:drive:version:readonly",
+      "drive:file.like:readonly",
+      "drive:file.meta.sec_label.read_only",
+      "drive:file:download",
+      "drive:file:favorite",
+      "drive:file:favorite:readonly",
+      "drive:file:upload",
+      "drive:file:view_record:readonly",
+      "event:ip_list",
+      "im:chat.access_event.bot_p2p_chat:read",
+      "im:chat.announcement:read",
+      "im:chat.announcement:write_only",
+      "im:chat.chat_pins:read",
+      "im:chat.chat_pins:write_only",
+      "im:chat.collab_plugins:read",
+      "im:chat.collab_plugins:write_only",
+      "im:chat.managers:write_only",
+      "im:chat.members:read",
+      "im:chat.members:write_only",
+      "im:chat.moderation:read",
+      "im:chat.tabs:read",
+      "im:chat.tabs:write_only",
+      "im:chat.top_notice:write_only",
+      "im:chat:delete",
+      "im:chat:moderation:write_only",
+      "im:chat:read",
+      "im:chat:update",
+      "im:message",
+      "im:message.group_msg:get_as_user",
+      "im:message.p2p_msg:get_as_user",
+      "im:message.pins:read",
+      "im:message.pins:write_only",
+      "im:message.reactions:read",
+      "im:message.reactions:write_only",
+      "im:message.urgent.status:write",
+      "im:message:readonly",
+      "im:message:recall",
+      "im:message:update",
+      "im:special_focus",
+      "offline_access",
+      "search:docs:read",
+      "search:message",
+      "sheets:spreadsheet.meta:read",
+      "sheets:spreadsheet.meta:write_only",
+      "sheets:spreadsheet:create",
+      "sheets:spreadsheet:read",
+      "sheets:spreadsheet:write_only",
+      "slides:presentation:create",
+      "slides:presentation:read",
+      "slides:presentation:update",
+      "slides:presentation:write_only",
+      "space:document.event:read",
+      "space:document:create",
+      "space:document:delete",
+      "space:document:move",
+      "space:document:retrieve",
+      "space:document:shortcut",
+      "space:folder:create",
+      "wiki:member:create",
+      "wiki:member:retrieve",
+      "wiki:member:update",
+      "wiki:node:copy",
+      "wiki:node:create",
+      "wiki:node:move",
+      "wiki:node:read",
+      "wiki:node:retrieve",
+      "wiki:node:update",
+      "wiki:setting:read",
+      "wiki:setting:write_only",
+      "wiki:space:read",
+      "wiki:space:retrieve",
+      "wiki:space:write_only",
+      "wiki:wiki:readonly"
+    ]
+  }
+}

package/dist/setup/register-app.d.ts

@@ -0,0 +1,46 @@
+export type RegisterBrand = 'feishu' | 'lark';
+export type RegisterAppOk = {
+    ok: true;
+    appId: string;
+    appSecret: string;
+    brand: RegisterBrand;
+};
+export type RegisterAppErr = {
+    ok: false;
+    /**
+     * - `aborted`: 用户 Ctrl-C / 主动取消
+     * - `expired`: 二维码过期 (默认 10 分钟)
+     * - `denied`: 用户在浏览器里拒绝
+     * - `network`: 网络错误 / 端点不可达
+     * - `unknown`: 其它 (含 SDK 抛非预期错误)
+     */
+    error: 'aborted' | 'expired' | 'denied' | 'network' | 'unknown';
+    /** 给用户看的简短错误描述, 不含 secret. */
+    message: string;
+};
+export type RegisterAppResult = RegisterAppOk | RegisterAppErr;
+export interface RegisterAppOptions {
+    /** 取消信号 (Ctrl-C 时填充). */
+    signal?: AbortSignal;
+    /**
+     * 渲染前回调, 测试时可注入静默打印. 默认在 stdout 打印二维码 + 链接.
+     */
+    onQRCodeReady?: (info: {
+        url: string;
+        expireIn: number;
+    }) => void;
+    /** 状态变更回调, 主要用于"已切换到 Lark 域名"提示. */
+    onStatusChange?: (info: {
+        status: string;
+        interval?: number;
+    }) => void;
+}
+/**
+ * 尝试扫码建应用. 任何失败都返回 RegisterAppErr (不抛), 调用方可以回退手动粘.
+ *
+ * Secret 安全约束:
+ * - SDK 返回的 client_secret 只放进返回值, 不打印, 不写日志
+ * - 错误链里只放错误 code / 阶段, 不带 secret
+ */
+export declare function tryRegisterApp(opts?: RegisterAppOptions): Promise<RegisterAppResult>;
+//# sourceMappingURL=register-app.d.ts.map

package/dist/setup/register-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-app.d.ts","sourceRoot":"","sources":["../../src/setup/register-app.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE9C,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,aAAa,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,KAAK,CAAC;IACV;;;;;;OAMG;IACH,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IAChE,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,cAAc,CAAC;AAE/D,MAAM,WAAW,kBAAkB;IACjC,yBAAyB;IACzB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAClE,oCAAoC;IACpC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACxE;AAiBD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA8C9F"}

package/dist/setup/register-app.js

@@ -0,0 +1,87 @@
+/**
+ * 飞书扫码建应用 — 对接 `@larksuiteoapi/node-sdk` 的 `registerApp`.
+ *
+ * 走 OAuth 2.0 Device Flow (RFC 8628):
+ *   1. SDK 向 `accounts.feishu.cn/oauth/v1/app/registration` 发 `action=begin`
+ *      请求 (`archetype=PersonalAgent`), 拿到 device_code + 二维码 URL
+ *   2. 在终端渲染二维码 + 链接, 等用户扫码
+ *   3. SDK 轮询同端点 `action=poll` 直到拿到 client_id + client_secret
+ *      (=AppID + AppSecret)
+ *
+ * 注意:
+ * - 这个端点 archetype 写死 `PersonalAgent`, 但实测 PersonalAgent 应用是
+ *   可以挂 bot 能力的 (`zarazhangrui/feishu-claude-code-bridge` 在用).
+ * - 建出来的应用 **没有** 声明 botmux 需要的 scope, 用户仍要在开放平台
+ *   「权限管理 → 批量导入/导出权限」粘贴 ~/.botmux/lark-scopes.json (setup
+ *   末尾会自动写一份) 一次性提交审批. 事件订阅 + bot 能力维护者实测默认
+ *   配好, 收不到消息时见 README 的 fallback 自查清单.
+ * - secret 永远不打印; 错误只暴露 error code / 阶段标签, 不暴露 secret.
+ */
+import { registerApp } from '@larksuiteoapi/node-sdk';
+import qrcode from 'qrcode-terminal';
+function defaultPrintQRCode(info) {
+    const mins = Math.max(1, Math.round(info.expireIn / 60));
+    process.stderr.write('\n请用飞书 App 扫码完成应用创建：\n\n');
+    qrcode.generate(info.url, { small: true }, (qr) => process.stderr.write(qr + '\n'));
+    process.stderr.write(`\n二维码有效期约 ${mins} 分钟。也可在浏览器打开：\n  ${info.url}\n\n`);
+}
+function defaultPrintStatus(info) {
+    if (info.status === 'domain_switched') {
+        process.stderr.write('识别到国际版租户, 已切换到 larksuite.com 域名继续轮询。\n');
+    }
+    else if (info.status === 'slow_down' && info.interval) {
+        process.stderr.write(`轮询过快, 间隔自动调整到 ${info.interval}s。\n`);
+    }
+}
+/**
+ * 尝试扫码建应用. 任何失败都返回 RegisterAppErr (不抛), 调用方可以回退手动粘.
+ *
+ * Secret 安全约束:
+ * - SDK 返回的 client_secret 只放进返回值, 不打印, 不写日志
+ * - 错误链里只放错误 code / 阶段, 不带 secret
+ */
+export async function tryRegisterApp(opts = {}) {
+    const onQR = opts.onQRCodeReady ?? defaultPrintQRCode;
+    const onStatus = opts.onStatusChange ?? defaultPrintStatus;
+    try {
+        const result = await registerApp({
+            signal: opts.signal,
+            source: 'botmux',
+            onQRCodeReady: onQR,
+            onStatusChange: onStatus,
+        });
+        if (!result.client_id || !result.client_secret) {
+            return {
+                ok: false,
+                error: 'unknown',
+                message: 'SDK 返回的 client_id/client_secret 为空',
+            };
+        }
+        const brand = result.user_info?.tenant_brand === 'lark' ? 'lark' : 'feishu';
+        return {
+            ok: true,
+            appId: result.client_id,
+            appSecret: result.client_secret,
+            brand,
+        };
+    }
+    catch (err) {
+        // SDK 抛 LarkChannelError, code 字段对齐 RFC 8628 的 device flow 错误
+        const code = err?.code ?? '';
+        const rawMsg = err?.message ?? String(err);
+        // SDK 不会把 secret 放进 message, 但保险起见再过一次
+        const safeMsg = rawMsg.replace(/[a-zA-Z0-9_-]{30,}/g, '***');
+        if (code === 'abort')
+            return { ok: false, error: 'aborted', message: '用户取消扫码' };
+        if (code === 'expired_token')
+            return { ok: false, error: 'expired', message: '二维码已过期, 请重试' };
+        if (code === 'access_denied')
+            return { ok: false, error: 'denied', message: '用户在浏览器里拒绝授权' };
+        // 网络层错误 (axios) — 没固定 code, 看 message
+        if (/ETIMEDOUT|ECONNREFUSED|ENOTFOUND|ECONNRESET|network/i.test(rawMsg)) {
+            return { ok: false, error: 'network', message: `网络错误: ${safeMsg}` };
+        }
+        return { ok: false, error: 'unknown', message: safeMsg };
+    }
+}
+//# sourceMappingURL=register-app.js.map

package/dist/setup/register-app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-app.js","sourceRoot":"","sources":["../../src/setup/register-app.ts"],"names":[],"mappings":"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"}

package/dist/setup/verify-permissions.d.ts

@@ -0,0 +1,115 @@
+export type Brand = 'feishu' | 'lark';
+export interface RequiredScope {
+    /** 飞书 scope 名 (`im:message` 等) */
+    name: string;
+    /** 给用户看的中文说明 */
+    desc: string;
+    /**
+     * `critical` = 不开通 botmux 核心功能无法工作 (收发消息).
+     * 非 critical 的 scope 缺失只 WARN, 不阻断启动.
+     */
+    critical: boolean;
+}
+/**
+ * botmux 运行所需的 scope. 这里**只用于检测/提示**, 不用于自动申请——飞书
+ * `scope.apply` 只能提交"已声明但未授权"的, 没法给应用 manifest 加新声明.
+ * scope 选择必须用户去开放平台勾.
+ */
+export declare const BOTMUX_REQUIRED_SCOPES: RequiredScope[];
+export interface RemainingStep {
+    title: string;
+    /** 飞书开放平台深链, 用户点了直接到对应页 */
+    url: string;
+}
+export declare function buildScopeDeepLink(appId: string, scopeName: string, brand?: Brand): string;
+export declare function buildEventSubDeepLink(appId: string, brand?: Brand): string;
+export declare function buildAppHomeDeepLink(appId: string, brand?: Brand): string;
+export type CredentialValidation = {
+    ok: true;
+    tenantAccessToken: string;
+    tokenExpiresIn: number;
+} | {
+    ok: false;
+    error: 'invalid_credentials' | 'network' | 'unknown';
+    message: string;
+};
+/**
+ * 用 AppID/Secret 取一次 tenant_access_token, 验证凭证可用.
+ *
+ * Secret 不进 error.message: 错误信息只来自飞书返回的 msg 字段或 axios 错误类型.
+ *
+ * Codex review #3: 加 AbortController + 总超时. 网络半挂时 `botmux setup` /
+ * `botmux start` 不能无限卡住; 超时归类为 network, 这样 setup 走"凭证校验失败
+ * 不写盘" 路径, start 走"network 只 WARN 继续"路径.
+ */
+export declare function validateCredentials(appId: string, appSecret: string, brand?: Brand, opts?: {
+    budgetMs?: number;
+    signal?: AbortSignal;
+}): Promise<CredentialValidation>;
+export type ScopeCheckResult = {
+    ok: true;
+    granted: string[];
+    missingCritical: RequiredScope[];
+    missingOptional: RequiredScope[];
+} | {
+    ok: false;
+    /**
+     * - `need_self_manage`: 调 scope.list 被拒, 应用缺 `application:application:self_manage`
+     *   (鸡生蛋: 没这个 scope 就查不到 scope 列表)
+     * - `network` / `unknown`: 其它失败
+     */
+    error: 'need_self_manage' | 'network' | 'unknown';
+    message: string;
+};
+/**
+ * 列出应用的 scope grant 状态, 比对 BOTMUX_REQUIRED_SCOPES.
+ *
+ * **不在主路径使用** — 待 spike 用真实/可复现 mock 证明 grant_status 含义和
+ * 状态闭环后再启用. 当前主路径只输出"剩余步骤 + 深链", 不做 grant_status 判定.
+ *
+ * scope.list 返回 shape (SDK type):
+ *   `{ data: { scopes: [{ scope_name, grant_status, scope_type }] } }`
+ * grant_status 含义未在官方文档明确, 但社区 SDK / 实测一般约定:
+ *   1 = 已申请未生效, 2 = 已生效. 启用前 spike 务必确认这个映射.
+ */
+export declare function checkRequiredScopes(appId: string, appSecret: string, brand?: Brand): Promise<ScopeCheckResult>;
+/**
+ * 触发管理员审批 (把"已声明但未授权"的 scope 提交).
+ *
+ * **不在主路径使用** — 见模块顶部注释. 文档表明它无法添加新 scope 到 manifest,
+ * 所以即使调成功也不能绕过"用户去开放平台勾 scope". 留作 spike 验证状态闭环
+ * 后的可选自动触发能力.
+ *
+ * 文档/SDK 显示无请求体. 错误码:
+ * - 212001: 剩余权限为高敏, 无法申请
+ * - 212002: 无可申请的 scope (manifest 全部已授权或为空)
+ * - 212003: 申请次数超限 (同租户同版本 > 10 次)
+ * - 212004: 重复申请
+ */
+export interface ApplyScopesResult {
+    /**
+     * - `submitted`: 申请已提交 (code=0). 是否被管理员审批通过需另查 `scope.list`.
+     * - `nothing_to_apply`: 212002, manifest 没有"已声明但未授权"的 scope.
+     * - `already_applied`: 212004, 重复申请.
+     * - `over_limit`: 212003, 同租户同版本 > 10 次申请.
+     * - `super_scope_only`: 212001, 剩余为高敏权限不可申请.
+     * - `timeout`: 调用本身没在 budgetMs 内返回.
+     * - `error`: 其它失败.
+     */
+    status: 'submitted' | 'nothing_to_apply' | 'already_applied' | 'over_limit' | 'super_scope_only' | 'timeout' | 'error';
+    code?: number;
+    msg?: string;
+}
+export declare function applyScopesUnverified(appId: string, appSecret: string, opts?: {
+    brand?: Brand;
+    budgetMs?: number;
+    signal?: AbortSignal;
+}): Promise<ApplyScopesResult>;
+/**
+ * setup 后 "还要手动点的步骤" 结构化数据. 跟 cli.ts 的 printRemainingSteps + README
+ * "5 分钟快速接入" 一致: 主线就两步 (权限申请 + 按需重定向 URL); PersonalAgent
+ * 应用默认订阅事件 + bot 能力, 不在主线提示, 收不到消息时见 README 的 fallback
+ * 自查清单.
+ */
+export declare function buildRemainingSteps(appId: string, brand?: Brand): RemainingStep[];
+//# sourceMappingURL=verify-permissions.d.ts.map

package/dist/setup/verify-permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-permissions.d.ts","sourceRoot":"","sources":["../../src/setup/verify-permissions.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtC,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAa,EAQjD,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,GAAE,KAAgB,GAAG,MAAM,CAGpG;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,KAAgB,GAAG,MAAM,CAGpF;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,KAAgB,GAAG,MAAM,CAGnF;AAID,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,qBAAqB,GAAG,SAAS,GAAG,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzF;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,KAAgB,EACvB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GACrD,OAAO,CAAC,oBAAoB,CAAC,CA0D/B;AAID,MAAM,MAAM,gBAAgB,GACxB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,EAAE,aAAa,EAAE,CAAC;IACjC,eAAe,EAAE,aAAa,EAAE,CAAC;CAClC,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV;;;;OAIG;IACH,KAAK,EAAE,kBAAkB,GAAG,SAAS,GAAG,SAAS,CAAC;IAClD,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEN;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,KAAgB,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAiC3B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;OAQG;IACH,MAAM,EACF,WAAW,GACX,kBAAkB,GAClB,iBAAiB,GACjB,YAAY,GACZ,kBAAkB,GAClB,SAAS,GACT,OAAO,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GACpE,OAAO,CAAC,iBAAiB,CAAC,CAmC5B;AAID;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,KAAgB,GAAG,aAAa,EAAE,CAa3F"}