mytglib 1.1.3 → 1.1.5

package/README.md

@@ -171,7 +171,7 @@ const updates = await core.submitCredentials({
 const jsonFilePath = await core.syncSessionJson();
 ```
 
-`syncSessionJson()` 无参数并返回 JSON 文件路径。JSON 中的 `session_str` 为可与 Telethon StringSession v1 兼容的字符串，`reg_time` 按中国标准时间转为 `YYYY-MM-DD`；当前转换仅支持项目使用的 IPv4 主 DC。底层 `.session` 仍是 mtcute SQLite，不会被转换成 Telethon SQLite。输出文件包含 auth key 和明文两步验证密码，会以 `0600` 权限原子替换，必须与 `.session` 一样按密码保护。
+`syncSessionJson()` 无参数并返回 JSON 文件路径。JSON 中的 `session_str` 为可与 Telethon StringSession v1 兼容的字符串，`reg_time` 按中国标准时间转为 `YYYY-MM-DD`；当前转换仅支持项目使用的 IPv4 主 DC。底层 `.session` 仍是 mtcute SQLite，不会被转换成 Telethon SQLite。输出文件包含 auth key 和明文两步验证密码，会通过临时文件原子替换；文件权限由运行环境的默认配置决定。
 
 ## 手机号状态账号池
 
@@ -181,7 +181,7 @@ const jsonFilePath = await core.syncSessionJson();
 
 Pool 使用消费者模式：外部请求只消费已经连接的 `READY` 槽位，不会在请求路径中临时连接
 Telegram。创建 Pool 和后续补槽均为异步操作，因此进程刚启动、账号刚导入或资源已达上限而没有
-`READY` 账号时，检测会立即返回 `BUSY`，不会排队等待建连。
+`READY` 账号时，检测会立即返回 `OTHER_ERROR`，不会排队等待建连。
 
 ### 初始化与导入
 
@@ -202,9 +202,9 @@ const account = await pool.importAccount({
 console.log(account.accountId, account.runtimeStatus);
 ```
 
-`databasePath` 必须是绝对文件路径。数据库目录和文件分别使用 `0700`、`0600` 权限；Pool 会把
-账号连接所需的 auth key 和 JSON Metadata 明文持久化到 SQLite，因此应把数据库目录视为密钥目录
-进行保护。`.session` 与 JSON 必须属于同一个有效的 Telethon 账号，导入时会严格核对 auth key、
+`databasePath` 必须是绝对文件路径，目录和文件权限由运行环境的默认配置决定。Pool 会把
+账号连接所需的 auth key 和 JSON Metadata 明文持久化到 SQLite。`.session` 与 JSON 必须属于
+同一个有效的 Telethon 账号，导入时会严格核对 auth key、
 DC、账号身份和手机号。Pool 只接受 Telegram 官方移动端凭据：Android 必须使用 `app_id: 4`
 及其官方 `app_hash`，iOS 必须使用 `app_id: 8` 及其官方 `app_hash`；TDesktop、自定义 API ID
 或平台与 API 凭据不匹配的 JSON 会在建立 Telegram 连接前直接拒绝。当前不支持代理。
@@ -235,32 +235,42 @@ const response = await pool.checkPhoneStatus({
   abortSignal: new AbortController().signal,
 });
 
-if (response.status === "RESULT") {
-  console.log(response.result, response.checkedAt, response.cached);
-} else {
-  console.log(`线路忙，请在 ${response.retryAfterSeconds} 秒后重试`);
-}
+console.log(response.status, response.waitTime, response.error);
 ```
 
-对外只有两种返回形态：
+返回对象固定使用一套扁平结构：
 
 ```js
 {
-  status: "RESULT",
+  waitTime: 0,
   phone: "+12025550123",
-  result: "PHONE_NUMBER_OCCUPIED",
-  checkedAt: "2026-08-13T00:00:00.000Z",
-  cached: false,
+  startedAt: "2026-08-13T00:00:00.000Z",
+  endedAt: "2026-08-13T00:00:00.120Z",
+  durationMs: 120,
+  status: "PHONE_NUMBER_OCCUPIED",
+  error: null,
 }
-
-{ status: "BUSY", retryAfterSeconds: 1 }
 ```
 
+`status` 只会是 `PHONE_NUMBER_OCCUPIED`、`PHONE_NUMBER_NO_OCCUPIED`、
+`PHONE_NUMBER_INVALID`、`PHONE_NUMBER_BANNED`、`FLOOD_WAIT` 或 `OTHER_ERROR`。
+`FLOOD_WAIT` 的等待秒数写入 `waitTime`；其他状态的 `waitTime` 为 `0`。
+未映射到上述业务状态的检测异常会被捕获并以 `OTHER_ERROR` 正常返回，`error` 仅保留可用的 `message`、`name`、
+`code`、`text` 和 `seconds`。
+
 单次检测总期限固定为 10 秒。账号触发 `FLOOD_WAIT` 后会按 Telegram 返回的等待秒数退出暖槽并
 进入冷却，Pool 随即从库存异步补入其他账号；当前请求最多再换用一个已经存在的 `READY` 账号，
-第二次仍未得到明确结果时返回 `BUSY`。`PHONE_NUMBER_FLOOD` 只保护目标手机号 5 分钟，不处罚
+第二次仍触发洪水时返回 `FLOOD_WAIT`。`PHONE_NUMBER_FLOOD` 只保护目标手机号 5 分钟，不处罚
 账号。明确检测结果缓存 5 分钟，最多保存 10,000 条；同一手机号的并发请求会合并为一次检测，
-基础设施错误不缓存，并统一按 `BUSY` 返回；也不提供强制刷新。
+基础设施错误不缓存，也不提供强制刷新。
+
+`abortSignal` 只取消当前调用方等待，并以 `OTHER_ERROR` 返回取消原因；它不会中断已经启动的
+single-flight RPC。即使当前只有一个等待者，后台检测仍可完成并写入明确结果缓存。调用开始前已经
+取消的 signal 会在读取缓存前返回，不会命中旧结果或启动新 RPC。
+
+按照当前业务规则，`403 RECAPTCHA_CHECK_signup`（含 site key 后缀）直接判定为
+`PHONE_NUMBER_NO_OCCUPIED`。Pool 不求解、不重放 challenge；它会回收触发 challenge 的槽位并从库存
+异步补槽。其他 reCAPTCHA action 仍按 `OTHER_ERROR` 返回。
 
 ### 管理与运行状态
 
@@ -333,13 +343,15 @@ await pool.close({ drainTimeoutMs: 10_000 });
 
 `close()` 会先等待正在执行的管理和检测操作；超过 drain deadline 后取消未完成操作，再销毁所有
 Telegram 客户端、定时器、缓存、SQLite 连接和 owner lock。关闭后的 Pool 不能复用，应重新调用
-`createPhoneStatusPool()`。
+`createPhoneStatusPool()`。如果强制关闭宽限期结束时仍有底层客户端销毁任务，`close()` 返回
+`POOL_CLOSE_TIMEOUT` 并保持 SQLite repository 和 owner lock；后台销毁结束后可再次调用 `close()`
+完成资源释放。
 
 ### Rust API
 
 Rust 实现从 `grammers_core` 根模块导出 `create_phone_status_pool()`、`PhoneStatusPool` 及相关
-输入、响应和状态类型。调度、持久化格式、暖槽策略及检测业务响应的 `RESULT`/`BUSY` 边界与上述
-Node.js 实现一致。目标手机号格式无效属于明确检测结果，返回
+输入、响应和状态类型。调度、持久化格式和暖槽策略与 Node.js 实现一致。Rust Pool 仍使用
+`RESULT`/`BUSY` 调度响应。目标手机号格式无效属于明确检测结果，返回
 `Ok(PhoneStatusCheckResponse::Result { result: PhoneNumberInvalid, .. })`；没有 `READY` 账号、检测
 期限耗尽、目标号码触发 `PHONE_NUMBER_FLOOD` 或检测基础设施失败均返回
 `Ok(PhoneStatusCheckResponse::Busy { .. })`。创建和管理操作的无效输入、调用取消、Pool
@@ -494,9 +506,11 @@ Rust 的 `timeout_ms` 覆盖文件读取、只读会话加载、连接及目标
 返回对象固定包含 `waitTime`、原样传入的 `phone`、ISO 时间字符串 `startedAt`/`endedAt`、
 `durationMs`、`status` 和 `error`。`status` 可能为 `PHONE_NUMBER_OCCUPIED`、
 `PHONE_NUMBER_NO_OCCUPIED`、`PHONE_NUMBER_INVALID`、`PHONE_NUMBER_BANNED`、`FLOOD_WAIT`
-或 `OTHER_ERROR`。`RECAPTCHA_CHECK_signup` 不会触发求解或再次请求，也不用于推断号码状态，而是按
-`OTHER_ERROR` 返回；`FLOOD_WAIT` 的秒数写入 `waitTime`；其他异常同样不会向外抛出，而是在 `error`
-中保留可用的 `message`、`name`、`code`、`text` 和 `seconds`。
+或 `OTHER_ERROR`。`RECAPTCHA_CHECK_signup` 不会触发求解或再次请求，而是按当前业务规则返回
+`PHONE_NUMBER_NO_OCCUPIED`；`FLOOD_WAIT` 的秒数写入 `waitTime`；其他异常同样不会向外抛出，而是在 `error`
+中保留可用的 `message`、`name`、`code`、`text` 和 `seconds`。sender cleanup 失败始终返回
+`OTHER_ERROR` 且 `waitTime` 为 `0`；若目标 RPC 同时失败，合并后的 message 会包含 cleanup 原因，并保留
+可用的 RPC 关键字段。
 
 授权成功后可调用 Telegram 官方的 [`account.getAuthorizations`](https://core.telegram.org/method/account.getAuthorizations)
 获取当前账号的全部登录会话，并把响应保存到同目录的 `<session stem>.authorizations.json`：