mytglib 2.0.5 → 2.1.1

package/README.md

@@ -2,6 +2,8 @@
 
 `mytglib` 是对 `@mtcute/node` 登录流程的轻量封装，提供 Android/iOS 客户端配置、手机号与代理检查、验证码登录、结果消息解析和设备模型生成。
 
+当前版本：Node.js `mytglib 2.1.1`，Rust `grammers-core 0.3.1`。本次仅递增补丁版本，功能首次引入版本仍以各节说明为准。
+
 ## 环境
 
 - Node.js 20、22、23、24、25 或 26（与 `better-sqlite3@12.11.1` 支持范围一致）
@@ -150,7 +152,7 @@ const iosCore = new CoreClient({
   phone: "+12025550123",
   proxy: { type: "http", host: "127.0.0.1", port: 8080 },
   sessionDirPath: resolve("telegram-sessions"),
-  langCode: "en",
+  langCode: "Custom_1",
   appVersion: "12.8.1 (33181) ",
   overrideLayer: 227,
   deviceTokenResolver: async () => ({ token: "AQIDBA==" }),
@@ -160,8 +162,48 @@ const iosCore = new CoreClient({
 覆盖值仅适用于 iOS；`appVersion` 必须是非空字符串，`overrideLayer` 必须是正数 int32。Rust fork
 同样只把 `app_version` 用于 `initConnection`，协议 layer 始终使用编译期 `tl::LAYER`。Node.js 和 Rust
 新写入的 `override_layer` Metadata 均记录当前真实 codec layer（当前为 229），不记录历史选择值。
-`langCode` 同样只支持 iOS，并且必须来自公开的 `iosLangPackLanguages`；省略时继续根据
-手机号自动选择。手工覆盖只改变 Telegram `langCode`，`systemLangCode` 仍按手机号地区推断。
+Node.js 从 `2.1.0` 起与 Rust `grammers-core 0.3.0` 使用相同的 iOS 自定义语言规则：
+`langCode` 去除首尾空白后必须为 1–10 位 ASCII 字母、数字、连字符或下划线，并保留大小写。
+自定义值不受 `iosLangPackLanguages` 限制；该公开语言池仍用于默认映射和查询。
+两端省略时均根据手机号自动选择；手工覆盖只改变 Telegram `langCode`，`systemLangCode`
+仍按手机号地区推断。新 Session 保存自定义值并用于 JSON 导出，已有 Session 保留首次快照。
+Android 仍不支持覆盖。
+Rust 的原始 RPC 观察接口、源码兼容性变化和 Git 依赖更新流程见
+[grammers-core 0.3.0](docs/grammers-core-0.3.0.md)。
+
+Node.js `2.1.0` 新增可选的 `rpcErrorObserver`，适用于 Android 和 iOS，省略时不安装观察中间件：
+
+```js
+let observedFloodWait = false;
+const core = new CoreClient({
+  clientType: "ios",
+  // phone、proxy、sessionDirPath 和 token resolver 按上面的初始化示例配置。
+  rpcErrorObserver: ({ code, rawMessage }) => {
+    if (code === 420 && /^FLOOD_(?:PREMIUM_|TEST_PHONE_)?WAIT_\d+$/.test(rawMessage)) {
+      observedFloodWait = true;
+    }
+  },
+});
+// 在业务操作结束后读取 observedFloodWait，持久化和按任务去重由调用方负责。
+```
+
+回调接收冻结的 `{ code, rawMessage }` 快照；`rawMessage` 保留 `FLOOD_WAIT_17` 等原文，
+不会转换成底层 `RpcError.text` 的 `FLOOD_WAIT_%d` 模板。回调必须同步、快速返回，
+不得抛异常或返回 Promise；返回值被忽略，异步持久化应交给调用方。
+违反契约抛出的异常会终止当前 RPC 并向调用方传播，库不会静默吞掉，也不提供异常隔离。
+
+观察器使用现有 `@mtcute/node` 中间件，在重试/等待处理前观察每次可见的 RPC 错误，
+包括短 FLOOD_WAIT、服务器内部错误、reCAPTCHA 初始挑战及包装请求错误；不增加重试、
+不替换响应。客户端销毁后重新初始化仍保留该配置。`onLog` 继续负责操作日志，不能替代本回调。
+覆盖范围有以下边界：
+
+- 本地限流缓存、连接异常和 token 服务商错误不触发观察。
+- `@mtcute` 底层已处理的 DC 迁移、连接初始化等错误可能不会到达中间件。
+- `400 TIMEOUT` 无法区分本地合成结果与服务器响应，统一排除；同名同码的服务器错误也不会通知。
+- 取消后未到达中间件的响应不可见；等待中取消不会撤销此前已发生的观察。
+
+这些边界与 Rust sender 观察点不同，不保证两端收到完全相同的错误集合；本库不修改
+`@mtcute` 的重试、超时、取消或迁移实现。同一业务操作可能触发多次回调，库不做业务去重。
 
 `sendCode()` 可选接收 `codeSettings` 对象，用于覆盖本次 `auth.sendCode` 请求的五个布尔能力字段。Android 保持原有默认值：`allowFirebase`、`allowFlashcall`、`allowMissedCall` 为 `true`，`currentNumber`、`unknownNumber` 为 `false`。
 
@@ -185,6 +227,8 @@ reCAPTCHA 由客户端的全局 network middleware 处理，不限于 `auth.send
 
 Rust `grammers_core` 对初始 `auth.sendCode` 及其自动生成的 `invokeWithReCaptcha(auth.sendCode)` 额外设置完整 frame 写出后的 20 秒响应期限。连接类失败会先关闭当前 DC sender，再用同一序列化请求和同一 reCAPTCHA token 在新代理隧道上重放一次；明确的 Telegram RPC 错误、取消和第二次连接失败不会重放。该规则不改变 Node.js `@mtcute/node` 实现，也不适用于 `signIn`、`signUp` 或其他 RPC。
 
+Rust `verify_phone_code()` / `register()`（包括对应 `CoreOperation`）的每个授权步骤共用 60 秒期限，包含开始/结束日志回调、重连、DC 迁移、核验、退避和授权元数据处理；日志回调也响应取消和期限。未派发业务请求的结构化连接初始化超时最多额外重试 3 次；仅 `auth.signUp` 的 `500 REG_ID_GENERATE_FAILED` 最多额外重试 3 次，退避均为 2、5、5 秒。注册重放前直接调用 `users.getUsers(InputUserSelf)`：已授权则保存成功，只有明确 `401 AUTH_KEY_UNREGISTERED` 才允许重放该 500。发送结果未知时只核验、不重放。恢复次数或期限耗尽、核验失败时返回 `CoreError::AuthorizationRecoveryRequired`，保留原始错误和重试记录，超时丢弃在途调用时也不会丢失这些记录；`signUp` 返回非成功授权响应同样归为授权未知；取消保持 `CoreError::Aborted`。恢复复用原 Session 和参数，禁止额外 reCAPTCHA 求解，不重新取号或发码。调用方应将最终未知结果隔离，不在外层另开自动重试循环。Node.js 行为不变。
+
 `auth.sentCodePaymentRequired` 不是 RPC 错误，而是 `auth.sendCode` 的合法返回。它表示由于所在国家或运营商的短信验证成本较高，官方客户端必须先完成 Telegram Premium 购买流程才能继续登录或注册。原始响应中的 `storeProduct`、`premiumDays`、`currency` 和 `amount` 描述商品与价格，`phoneCodeHash` 保留后续授权上下文，`supportEmailAddress` 和 `supportEmailSubject` 用于联系支持。
 
 `sendCode()` 或 `verifyEmailCode()` 收到该响应时，会像保存 `phoneCodeHash` 一样把三个必需字段原子地挂载到 `core.inputStore`：`{ premiumDays, currency, amount }`。普通 `auth.sentCode`、`auth.sentCodeSuccess`、授权成功及成功销毁客户端时会清空该状态。
@@ -353,9 +397,12 @@ console.log(response.status, response.waitTime, response.error);
 返回的等待秒数退出暖槽并进入冷却，Pool 随即从库存异步补入其他账号。
 若暖槽返回冻结账号错误，Pool 会将该账号永久隔离并换用其他 `READY` 槽位；当前检测返回的错误仍保留
 Telegram 原始 `code = 420` 和错误文本。
-`PHONE_NUMBER_FLOOD` 是目标手机号级错误，不换槽重试，只保护目标手机号 5 分钟且不处罚账号。
-明确检测结果缓存 5 分钟，最多保存 10,000 条；同一手机号的并发请求会合并为一次检测，
-基础设施错误不缓存，也不提供强制刷新。
+`PHONE_NUMBER_FLOOD` 是目标手机号级错误，当前请求不换槽重试、不处罚账号，也不缓存错误；后续同号请求可重新检测。
+仅 `PHONE_NUMBER_OCCUPIED`、`PHONE_NUMBER_NO_OCCUPIED`、`PHONE_NUMBER_INVALID` 和
+`PHONE_NUMBER_BANNED` 的确定结果缓存 60 秒，最多保存 10,000 条；有效期从写入时计算，命中不续期。
+本地格式校验失败仍即时返回 `PHONE_NUMBER_INVALID`，不发起 RPC，也不占用结果缓存。
+同一手机号的并发请求会合并为一次检测；`FLOOD_WAIT`、`OTHER_ERROR` 等其他结果不缓存，
+共享检测结束后后续请求可重新检测，也不提供强制刷新。
 
 `abortSignal` 只取消当前调用方等待，并以 `OTHER_ERROR` 返回取消原因；它不会中断已经启动的
 single-flight RPC。即使当前只有一个等待者，后台检测仍可完成并写入明确结果缓存。调用开始前已经
@@ -489,6 +536,10 @@ Telegram 客户端、定时器、缓存、SQLite 连接和 owner lock。关闭
 
 ### Rust API
 
+同一个 Pool 还支持通过 `userId` 查询大约注册年月，Node.js 使用 `getRegistrationDate()`，Rust 使用
+`get_registration_date()`；暖槽授权、DeviceCheck 材料配置、并发与返回契约见
+[注册年月查询](docs/registration-date.md)。
+
 Rust 实现从 `grammers_core` 根模块导出 `create_phone_status_pool()`、`PhoneStatusPool` 及相关
 输入、响应和状态类型。调度、持久化格式和暖槽策略与 Node.js 实现一致。手机号检测统一返回
 扁平的 `PhoneStatusCheckResponse`，字段为 `wait_time`、`phone`、`started_at`、`ended_at`、