mytglib 1.0.0

package/README.md

@@ -0,0 +1,121 @@
+# mytglib
+
+`mytglib` 是对 `@mtcute/node` 登录流程的轻量封装，提供 Android/iOS 客户端配置、手机号与代理检查、验证码登录、结果消息解析和设备模型生成。
+
+## 环境
+
+- Node.js 20+
+- 执行登录或代理检查时，需要一个可连接 Telegram 主 DC 的 HTTP 或 SOCKS5 代理
+
+安装当前仓库依赖：
+
+```bash
+npm install
+```
+
+## 构建
+
+生成供发布和包根入口使用的 ESM 产物：
+
+```bash
+npm run build
+```
+
+构建结果位于 `dist/index.js`。Webpack 会打包本仓库源码，使用 Terser 压缩，并对标识符和字符串数组进行混淆；`@mtcute/node` 等运行时依赖保持为外部 ESM 依赖，不会重复打入产物。构建不生成 source map，发布包仅包含 `dist`、`README.md`、`package.json` 和许可证文件。
+
+## 离线示例
+
+无需网络即可检查手机号解析、随机设备参数、验证码设置和消息映射：
+
+```bash
+npm run example:inspect
+npm run example:inspect -- "+1 (202) 555-0123"
+```
+
+实现位于 `examples/inspect-config.js`。
+
+## 初始化与登录
+
+完整示例位于 `examples/login.js`。先查看所需环境变量：
+
+```bash
+npm run example:login -- --help
+```
+
+以 HTTP 代理运行 Android 登录：
+
+```bash
+TG_PHONE="+12025550123" \
+TG_PROXY_HOST="127.0.0.1" \
+TG_PROXY_PORT="8080" \
+TG_PROXY_TYPE="http" \
+TG_DEVICE_TOKEN="your-device-token" \
+npm run example:login
+```
+
+示例按服务端响应处理邮箱设置、邮箱验证码、手机验证码和新账号注册。reCAPTCHA 出现时会显示 `action` 与 `siteKey`，并等待输入外部移动端求解器返回的 token。
+
+## 基本 API
+
+下面是常见的短信验证码登录路径；邮箱设置、新账号注册等完整分支见 `examples/login.js`。
+
+```js
+import { resolve } from "node:path";
+import { CoreClient, getCallMessage } from "mytglib";
+
+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,
+});
+
+try {
+  await core.init();
+  let response = await core.sendCode();
+  console.log(getCallMessage(response));
+
+  if (response._ === "auth.sentCode") {
+    response = await core.verifyPhoneCode({ phoneCode: "12345" });
+    console.log(getCallMessage(response));
+  } else if (response._ === "auth.sentCodeSuccess") {
+    response = response.authorization;
+  }
+
+  if (response._ !== "auth.authorization") {
+    throw new Error(`Login did not complete: ${response._}`);
+  }
+
+  const config = await core.client.call({ _: "help.getConfig" });
+  console.log(config.thisDc);
+} finally {
+  await core.client?.destroy();
+}
+```
+
+`sessionDirPath` 是必传的会话主目录。路径已存在时必须是目录；路径不存在时会在初始化过程中递归创建。`init()` 会按照 `<主目录>/<+手机号>/<+手机号>.session` 创建 SQLite 会话文件，然后依次解析设备 token 并连接客户端。登录相关公共异步方法均返回原始 Telegram TL 响应；原始请求可通过已连接的 `core.client.call()` 发送。无论成功或失败，都应在 `finally` 中调用 `destroy()`，永久关闭连接、定时器和存储资源。
+
+## 代理检查
+
+```js
+import { checkProxy } from "mytglib";
+
+const result = await checkProxy({
+  clientType: "android",
+  proxy: "socks5://user:password@127.0.0.1:1080",
+  timeoutMs: 12_000,
+});
+
+console.log(result);
+```
+
+`checkProxy` 会并行检查所选平台的全部五个 Telegram 主 DC，并关闭每个已建立的连接。
+
+## 测试
+
+```bash
+npm test
+npm run test:coverage
+```