mytglib 1.0.0 → 1.1.0

package/README.md

@@ -63,17 +63,24 @@ npm run example:login
 import { resolve } from "node:path";
 import { CoreClient, getCallMessage } from "mytglib";
 
+const abortController = new AbortController();
 const core = new CoreClient({
   clientType: "android",
   phone: "+12025550123",
   proxy: { type: "http", host: "127.0.0.1", port: 8080 },
   sessionDirPath: resolve("telegram-sessions"),
-  deviceTokenResolver: async () => "your-device-token",
-  recaptchaMobileTokenResolver: async () => process.env.TG_RECAPTCHA_TOKEN,
+  timeout: 30_000,
+  maxRetryCount: 0,
+  abortSignal: abortController.signal,
+  deviceTokenResolver: async () => ({ token: "your-device-token" }),
+  recaptchaMobileTokenResolver: async () => ({
+    token: process.env.TG_RECAPTCHA_TOKEN,
+  }),
 });
 
 try {
   await core.init();
+
   let response = await core.sendCode();
   console.log(getCallMessage(response));
 
@@ -91,11 +98,17 @@ try {
   const config = await core.client.call({ _: "help.getConfig" });
   console.log(config.thisDc);
 } finally {
-  await core.client?.destroy();
+  await core.destroy();
 }
 ```
 
-`sessionDirPath` 是必传的会话主目录。路径已存在时必须是目录；路径不存在时会在初始化过程中递归创建。`init()` 会按照 `<主目录>/<+手机号>/<+手机号>.session` 创建 SQLite 会话文件，然后依次解析设备 token 并连接客户端。登录相关公共异步方法均返回原始 Telegram TL 响应；原始请求可通过已连接的 `core.client.call()` 发送。无论成功或失败，都应在 `finally` 中调用 `destroy()`，永久关闭连接、定时器和存储资源。
+`deviceTokenResolver` 和 `recaptchaMobileTokenResolver` 必须返回包含非空字符串 `token` 字段的对象，对象可保留求解服务返回的 `errorMessage`、`message` 等附加字段。无有效 token 时会抛出 `TypeError`，其 `cause` 是 resolver 返回的完整结果，调用方可据此读取附加错误信息；reCAPTCHA token 最长为 16,384 个字符。
+
+`timeout`、`maxRetryCount` 和 `abortSignal` 是所有 mytglib 登录 RPC 的统一调用参数。`timeout` 默认为 `30000`，必须是正安全整数毫秒；`maxRetryCount` 默认为 `0`，必须是非负安全整数；`abortSignal` 默认为 `undefined`，传入时必须是 `AbortSignal`。客户端创建后会通过原始 `TelegramClient.withParams()` 生成 `core.client`，登录流程和通过 `core.client.call()` 发出的请求都会使用这些参数。它们只作用于 RPC，不处理 `connect()` 超时，也不会取消正在进行的 `connect()`。
+
+`sessionDirPath` 是必传的会话主目录。路径已存在时必须是目录；路径不存在时会在初始化过程中递归创建。`init()` 会按照 `<主目录>/<+手机号>/<+手机号>.session` 创建 SQLite 会话文件，然后依次解析设备 token 并连接客户端。连接成功后可通过 `core.sessionFilePath` 直接取得当前客户端使用的 SQLite 文件路径；连接前该属性为 `null`。登录相关公共异步方法均返回原始 Telegram TL 响应。`core.rawClient` 保存原始 `TelegramClient`，只负责 `connect()`、`notifyLoggedIn()` 和 `destroy()`；`core.client` 保存 `withParams()` 返回的 RPC Proxy。`core.destroy()` 始终销毁 `rawClient`，不会在 `@mtcute/node` 0.31.0 的包装对象上调用 `destroy()`，从而避免私有字段错误。无论成功或失败，都应在 `finally` 中调用 `core.destroy()`，永久关闭连接、定时器和存储资源。销毁成功后两个客户端引用都会恢复为 `null`，SQLite 文件路径仍保留在 `core.sessionFilePath` 上。
+
+`sendEmailCode()`、`verifyEmailCode()`、`verifyPhoneCode()` 和 `register()` 会直接向 `onLog` 发出 `started`、`completed` 或 `failed` 事件。失败事件的 `error` 保留 Telegram RPC 错误的 `code`、`text` 和 `message`，方法本身也会原样抛出错误；验证码等调用参数不会写入日志。
 
 ## 代理检查