mytglib 2.0.7 → 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`。