lansenger-sdk-ts 1.0.0

package/README.zhHantHK.md

@@ -0,0 +1,501 @@
+[English](README.md) | [简体中文](README.zhHans.md) | [繁体中文](README.zhHant.md) | [繁体中文香港](README.zhHantHK.md) | [Français](README.fr.md)
+
+# lansenger-sdk-ts
+
+藍信（Lansenger）平臺的 TypeScript SDK——支援藍信應用、組織機械人及個人機械人。
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript 5+](https://img.shields.io/badge/TypeScript-5%2B-blue)](https://www.typescriptlang.org/)
+[![Node 18+](https://img.shields.io/badge/Node-18%2B-green)](https://nodejs.org/)
+
+> 零框架依賴——僅依賴 `node-fetch` (v2，CommonJS 相容)。可適配任何 Node.js 專案。
+
+## 支援的機械人類型
+
+| 機械人類型 | 認證 | WebSocket 入站 | 全部 API |
+|------------|------|-----------------|----------|
+| **藍信應用** | appToken + userToken | ✗（使用 webhook） | ✓ |
+| **組織機械人** | appToken + userToken | ✗（使用 webhook） | ✓ |
+| **個人機械人** | appToken | ✓（WebSocket） | ✓（非機械人 API 有部分限制） |
+
+三種機械人類型使用相同的認證機制：`appToken` 為所有 API 呼叫所必需；`userToken` 僅在特定使用者級操作時需要（使用者資訊、員工搜尋、日曆等）。
+
+## 功能特色
+
+- **非同步客戶端** — `LansengerClient` 提供 Promise 化 API
+- **憑證與令牌持久化** — `CredentialStore` 將 app_id、app_secret、URL、appToken、userToken 保存至檔案（重啟不丟失）
+- **OAuth2 使用者認證** — 建構授權 URL、換取 userToken、更新令牌
+- **組織與部門** — 組織資訊、部門詳情/子部門/員工列表
+- **員工與通訊錄** — 基本/詳細資訊、ID 映射、部門祖先鏈、搜尋
+- **訊息傳遞** — 3 種私聊通道（機械人、公眾號、人→人）+ 群聊，支援所有訊息類型，含 @提及和真人/機械人發送身分，加急提醒
+- **富卡片** — appCard（支援動態狀態更新）、oacard、linkCard、appArticles
+- **串流訊息** — SSE 即時投遞，專為 AI Agent 設計
+- **媒體上傳/下載** — 檔案、圖片、影片，自動偵測類型，媒體路徑取得
+- **訊息管理** — 撤回、動態卡片更新
+- **群組** — 建立、查詢資訊/成員/列表、成員檢查、更新設定與成員、解散
+- **日曆日程** — 主日曆、日程 CRUD + 更新、參會人管理 + 參會人元資料
+- **統一待辦** — 建立、更新、刪除、查詢、執行人管理、狀態統計
+- **回呼事件** — 25 種事件類型、結構化訊息解析、AES 解密（4.10.1.4）、SHA1 簽名驗證
+- **聊天讀取** — 取得聊天列表、取得聊天訊息（4.24 MCP）
+
+## 快速安裝
+
+```bash
+npm install lansenger-sdk-ts
+```
+
+開發模式：
+
+```bash
+git clone https://github.com/lansenger-pm/lansenger-sdk-ts.git
+cd lansenger-sdk-ts
+npm install
+npm run build
+npm test
+```
+
+## 1. 認證
+
+### appToken — 所有 API 呼叫所必需
+
+每個 SDK 方法都需要 `appToken`。客戶端使用 `app_id` + `app_secret` 自動取得並更新 appToken，你無需手動管理——`TokenManager` 處理整個生命週期：
+
+1. **首次呼叫** → 使用 app_id + app_secret 請求 `GET /v1/apptoken/create` → 回傳 `appToken`（有效期 2 小時）
+2. **後續呼叫** → 重用已緩存的 appToken 直到過期
+3. **Token 過期** → 透過同一端點自動更新
+
+```typescript
+import { LansengerClient } from "lansenger-sdk-ts";
+
+const client = new LansengerClient("你的-appid", "你的-secret");
+
+// 你也可以手動取得/撤銷 token
+const token = await client.getToken();
+client.invalidateToken(); // 強制下次呼叫時更新
+```
+
+### userToken — 僅特定端點需要
+
+`userToken` 代表特定藍信使用者的授權（透過 OAuth2 取得），僅在以下情況需要：
+- 使用者級資訊（fetchUserInfo、fetchStaffDetail、searchStaff）
+- 日曆日程操作（fetchPrimaryCalendar、createSchedule 等）
+- 以真人發送身分進行群組操作
+
+### 取得憑證
+
+| 機械人類型 | 如何取得 app_id + app_secret |
+|------------|------------------------------|
+| **個人機械人** | 藍信桌面端 → 通訊錄 → 智慧機械人 → 個人機械人 → 點擊右側 ℹ️ 圖標（行動端不支援查看憑證） |
+| **藍信應用** | 在藍信開發者中心建立，可能需要向組織管理員申請 |
+| **組織機械人** | 在藍信開發者中心建立，可能需要向組織管理員申請 |
+
+### OAuth2 使用者級認證
+
+```typescript
+// 建構授權 URL——將使用者重定向到藍信通行證頁面
+const url = client.buildAuthorizeUrl("https://myapp.com/callback");
+
+// 使用者授權後，用 code 换取 userToken + refreshToken
+const tokenResult = await client.exchangeCode("回呼中的授權碼");
+
+// 更新過期的 userToken
+const newToken = await client.refreshUserToken(tokenResult.refresh_token!);
+
+// 取得使用者資料
+const userInfo = await client.fetchUserInfo(tokenResult.user_token!);
+```
+
+### 工廠方法
+
+```typescript
+// 從環境變數（LANSENGER_APP_ID、LANSENGER_APP_SECRET 等）
+const client = LansengerClient.fromEnv();
+
+// 從 LansengerConfig 物件
+const config = new LansengerConfig("appid", "secret", "https://open.e.lanxin.cn/open/apigw");
+const client = LansengerClient.fromConfig(config);
+
+// 從 CredentialStore（讀取持久化憑證）
+const client = LansengerClient.fromStore();
+```
+
+## 2. 組織與部門
+
+```typescript
+// 組織資訊
+const org = await client.fetchOrgInfo("orgId");
+
+// 部門層級
+const detail = await client.fetchDepartmentDetail("deptId");
+const children = await client.fetchDepartmentChildren("deptId");
+const staffs = await client.fetchDepartmentStaffs("deptId");
+```
+
+## 3. 員工與通訊錄
+
+```typescript
+// 基本員工資訊
+const staff = await client.fetchStaffBasicInfo("staffOpenId");
+
+// 詳細資料（建議使用 userToken）
+const detail = await client.fetchStaffDetail("staffOpenId", { user_token: "ut" });
+
+// 手機號 → staffId 映射
+const mapping = await client.fetchStaffIdMapping("orgId", "mobile", "13800138000");
+
+// 員工的部門祖先鏈
+const ancestors = await client.fetchDepartmentAncestors("staffOpenId");
+
+// 搜尋員工（需要 userToken）
+const results = await client.searchStaff("張三", { user_token: "ut" });
+
+// 組織額外欄位 ID
+const fields = await client.fetchOrgExtraFieldIds("orgId");
+```
+
+## 4. 訊息與媒體
+
+#### 機械人私聊——最常用
+
+```typescript
+const result = await client.sendText("staff123", "你好！");
+const result = await client.sendMarkdown("staff123", "**加粗**");
+const result = await client.sendFile("staff123", "/path/to/report.pdf");
+```
+
+#### 公眾號通道
+
+```typescript
+const result = await client.sendAccountMessage(
+  "text", { text: { content: "系統通知" } },
+  ["staff1", "staff2"], undefined,
+  { account_id: "524288-xxxx" },
+);
+```
+
+#### 人→人通道（需要 userToken）
+
+```typescript
+const result = await client.sendUserMessage(
+  "staff456", "text", { text: { content: "你好" } },
+  { user_token: "ut" },
+);
+```
+
+#### 群聊
+
+```typescript
+// 機械人 → 群組
+const result = await client.sendText("group123", "通知", { is_group: true });
+
+// 真人 → 群組（使用 userToken）
+const result = await client.sendGroupMessage(
+  "group123", "text", { text: { content: "我來處理" } },
+  { user_token: "ut" },
+);
+
+// 群聊 @提及
+const result = await client.sendText("group123", "重要！", { is_group: true, reminder_all: true });
+```
+
+#### 富卡片
+
+```typescript
+const result = await client.sendAppCard("staff123", "審批", { is_dynamic: true });
+const result = await client.sendLinkCard("staff123", "文章", "https://...");
+const result = await client.sendAppArticles("staff123", [{ title: "文章1", link: "..." }]);
+
+// 更新動態卡片狀態
+const result = await client.updateDynamicCard("msg123", { is_last_update: true });
+```
+
+#### 串流訊息（專為 AI Agent 設計）
+
+```typescript
+const result = await client.createStreamMessage("staff1", "staff", "stream-id-1");
+const result = await client.fetchStreamMessage("msg123");
+```
+
+#### 媒體
+
+```typescript
+// 上傳
+const upload = await client.uploadMediaFile("/path/to/file.pdf");
+
+// 下載
+const download = await client.downloadMediaFile("media123");
+
+// 保存至檔案
+const filePath = await client.downloadMediaToFile("media123", { target_path: "/tmp/file.pdf" });
+
+// 取得下載 URL 路徑 (4.5.3)
+const pathResult = await client.fetchMediaPathInfo("media123");
+
+// 撤回訊息
+const result = await client.revokeMessage(["msg1", "msg2"]);
+```
+
+#### 加急提醒 (4.6.14)
+
+```typescript
+import { REMINDER_TYPE_POPUP, REMINDER_TYPE_SMS } from "lansenger-sdk-ts";
+
+const result = await client.sendReminderMsg(
+  "msg123",
+  [REMINDER_TYPE_POPUP, REMINDER_TYPE_SMS],
+  ["staff1", "staff2"],
+);
+```
+
+## 5. 群組
+
+```typescript
+// 建立群組
+const group = await client.createGroup("專案討論", "orgId", { staff_id_list: ["s1", "s2", "s3"] });
+
+// 查詢資訊與成員
+const info = await client.fetchGroupInfo("groupOpenId");
+const members = await client.fetchGroupMembers("groupOpenId");
+const groups = await client.fetchGroupList();
+
+// 成員檢查
+const result = await client.checkIsInGroup("groupOpenId", { staff_id: "staff1" });
+
+// 更新設定
+await client.updateGroupInfo("groupId", { name: "新名稱", manage_mode: 1 });
+
+// 新增/移除成員
+await client.updateGroupMembers("groupId", { add_user_list: ["staff4"], del_user_list: ["staff3"] });
+
+// 解散群組（僅群主，4.28.6）
+await client.dismissGroup("groupId");
+```
+
+## 6. 日曆日程
+
+```typescript
+// 取得主日曆（需要 userToken 或 userId）
+const cal = await client.fetchPrimaryCalendar({ user_token: "ut" });
+
+// 建立日程
+const schedule = await client.createSchedule(
+  cal.calendar_id!, "團隊會議",
+  { date: "2024-01-15", time: "10:00", timeZone: "Asia/Shanghai" },
+  { date: "2024-01-15", time: "11:00", timeZone: "Asia/Shanghai" },
+  [{ staffId: "staff1", attendeeFlag: "required" }],
+  { user_token: "ut" },
+);
+
+// 取得/刪除日程
+const info = await client.fetchSchedule("cal1", "sch1", { user_token: "ut" });
+await client.deleteSchedule("cal1", "sch1", { user_token: "ut" });
+
+// 時間段內的日程列表（最多 42 天）
+const schedules = await client.fetchScheduleList("cal1", 1705276800000, 1707940800000, { user_token: "ut" });
+
+// 參會人管理
+const attendees = await client.fetchScheduleAttendees("cal1", "sch1", { user_token: "ut" });
+await client.addScheduleAttendees("cal1", "sch1", ["staff2"], { user_token: "ut" });
+await client.deleteScheduleAttendees("cal1", "sch1", ["staff2"], { user_token: "ut" });
+
+// 更新日程 (4.23.12)
+await client.updateSchedule("cal1", "sch1", { summary: "更新的會議", user_token: "ut" });
+
+// 更新參會人元資料 (4.23.17) — RSVP、顏色、忙/閒、提醒
+await client.updateScheduleAttendeeMeta("cal1", "sch1", {
+  rsvp_status: "accept", busy_free_state: "busy", remind_times: [5, 15], user_token: "ut",
+});
+```
+
+## 7. 統一待辦
+
+```typescript
+import { TODO_TYPE_APPROVAL, TODO_TODO_STATUS_DONE } from "lansenger-sdk-ts";
+
+// 建立待辦任務
+const todo = await client.createTodoTask(
+  "審批請求", "https://app.com/a/1", "https://pc.app.com/a/1",
+  ["staff1"], "org1", TODO_TYPE_APPROVAL,
+);
+
+// 更新狀態（11=待閱, 12=已閱, 21=待辦, 22=已辦）
+await client.updateTodoTaskStatus("taskId", TODO_TODO_STATUS_DONE, "org1");
+
+// 更新內容
+await client.updateTodoTask("taskId", "已更新", "l", "p", "org1");
+
+// 刪除（僅發送者可操作）
+await client.deleteTodoTask("taskId", "org1");
+
+// 查詢
+const listResult = await client.fetchTodoTaskList("org1");
+const task = await client.fetchTodoTaskById("taskId", "org1");
+const task = await client.fetchTodoTaskBySourceId("src1", "org1");
+const counts = await client.fetchTodoTaskStatusCounts("staff1", "org1");
+
+// 執行人管理
+await client.addExecutors(["staff2"], "org1", { todotask_id: "taskId" });
+await client.deleteExecutors(["staff2"], "org1", { todotask_id: "taskId" });
+const executors = await client.fetchExecutorList("taskId", "org1");
+await client.updateExecutorStatus(
+  [{ executorId: "staff1", todotaskId: "taskId", status: "22" }],
+  "org1",
+);
+```
+
+## 8. 聊天讀取 (4.24 MCP)
+
+```typescript
+// 取得聊天列表（私聊 + 羣聊）
+const chatList = await client.fetchChatList({ user_token: "ut" });
+
+// 取得聊天訊息
+const messages = await client.fetchChatMessages({
+  staff_id: "staff1", // 或 group_id: "group1"
+  user_token: "ut",
+});
+```
+
+## 9. 回呼事件
+
+SDK 同時支援純 JSON 和 AES 加密回呼載荷（藍信 API 規範 4.10.1.4）。
+
+### 配置
+
+設定 `encoding_key` 和 `callback_token`（來自藍信開發者中心回呼設定）：
+
+```typescript
+const client = new LansengerClient("appid", "secret", undefined, undefined, undefined, undefined, "BASE64_AES_KEY", "CALLBACK_TOKEN");
+```
+
+也可透過環境變數：`LANSENGER_ENCODING_KEY`、`LANSENGER_CALLBACK_TOKEN`。
+
+### 解析回呼載荷（自動辨識加密/明文）
+
+```typescript
+import { parseCallbackPayload } from "lansenger-sdk-ts";
+
+// 純 JSON webhook
+const events = parseCallbackPayload('{"events": [...]}');
+
+// AES 加密載荷（使用 encodingKey 自動解密）
+const events = parseCallbackPayload(encryptedData, {
+  encoding_key: "BASE64_AES_KEY",
+  known_app_id: "your-appid",
+});
+```
+
+### 驗證簽名
+
+```typescript
+import { verifyCallbackSignature } from "lansenger-sdk-ts";
+
+// sha1(sort(token, timestamp, nonce, dataEncrypt))
+const isValid = verifyCallbackSignature(
+  timestamp, nonce, signature, encodingKey,
+  { data_encrypt: encryptedData, callback_token: "CALLBACK_TOKEN" },
+);
+```
+
+### 事件類型
+
+```typescript
+const types = LansengerClient.getCallbackEventTypes(); // 25 種事件類型，13 個類別
+```
+
+## 訊息類型能力矩陣
+
+| msgType | Markdown | @提及 | 附件 | 私聊通道 | 羣聊 | 備註 |
+|---------|----------|-------|------|----------|------|------|
+| `text` | ✗ | ✓ (羣) | ✓ | 機械人、公眾號、人→人 | ✓ | 上限 6000 字節 |
+| `formatText` | ✓ | ✗ | ✗ | 僅人→人 | ✓ | formatType=1 支援 Markdown |
+| `oacard` | ✗ | ✗ | ✗ | 機械人、公眾號、人→人 | ✓ | 簡單卡片含欄位 |
+| `appCard` | ✓ (div) | ✗ | ✗ | 機械人、公眾號、人→人 | ✓ | 富卡片，支援動態更新 |
+| `linkCard` | ✗ | ✗ | ✗ | 機械人、公眾號 | ✓ | 連結預覽卡片 |
+| `appArticles` | ✗ | ✗ | ✗ | 僅機械人私聊 | ✓ | 文章列表（1+ 篇） |
+
+**羣聊**支援所有訊息類型。只有羣聊支援 @提及。
+
+## 配置
+
+### 環境變數
+
+| 變數 | 必填 | 說明 | 預設值 |
+|------|------|------|--------|
+| `LANSENGER_APP_ID` | ✓ | 應用/機械人 ID | — |
+| `LANSENGER_APP_SECRET` | ✓ | 應用/機械人 Secret | — |
+| `LANSENGER_API_GATEWAY_URL` | ✗ | API 网關 URL | `https://open.e.lanxin.cn/open/apigw` |
+| `LANSENGER_PASSPORT_URL` | ✗ | 通行證 URL（OAuth2） | — |
+| `LANSENGER_ENCODING_KEY` | ✗ | 回呼 AES 加密密鑰（Base64） | — |
+| `LANSENGER_CALLBACK_TOKEN` | ✗ | 回呼簽名令牌 | — |
+
+### 憑證與令牌持久化
+
+預設情況下，憑證和令牌僅保留在記憶體中（程式退出即消失）。啟用檔案持久化使用 `storePath`：
+
+```typescript
+import { LansengerClient, CredentialStore } from "lansenger-sdk-ts";
+
+// 自動持久化至 ~/.lansenger/sdk_state.json
+const client = new LansengerClient("appid", "secret", undefined, undefined, undefined, "~/.lansenger/sdk_state.json", "BASE64_AES_KEY", "CALLBACK_TOKEN");
+
+// 或從環境變數加持久化
+const client = LansengerClient.fromEnv("~/.lansenger/sdk_state.json");
+
+// 手動操作儲存
+const store = new CredentialStore("~/.lansenger/sdk_state.json");
+store.saveCredentials("app_id", "app_secret", "https://open.e.lanxin.cn/open/apigw");
+store.saveUserToken("user_token", "refresh_token");
+const token = store.loadAppToken(); // 過期則回傳 null
+```
+
+## 專案結構
+
+```
+lansenger-sdk-ts/
+├── src/
+│   ├── index.ts              # 全部导出
+│   ├── client.ts             # LansengerClient（非同步）
+│   ├── config.ts             # LansengerConfig
+│   ├── auth.ts               # TokenManager — appToken 生命週期管理
+│   ├── oauth.ts              # OAuth2 輔助
+│   ├── constants.ts          # API 端點、媒體類型、OAuth 範圍
+│   ├── exceptions.ts         # LansengerError 異常層級
+│   ├── models.ts             # 38+ 結果類型
+│   ├── http.ts               # doGet、doPost、doPostMultipart、parseApiResponse
+│   ├── urlHelpers.ts         # buildApiUrl (支援 pathVars)
+│   ├── contacts.ts           # 員工與組織資訊 API
+│   ├── departments.ts        # 部門 API
+│   ├── accountMessages.ts    # 公眾號通道
+│   ├── userMessages.ts       # 人→人通道
+│   ├── groupMessages.ts      # 羣聊通道
+│   ├── media.ts              # 上傳/下載
+│   ├── streaming.ts          # SSE 串流
+│   ├── persistence.ts        # CredentialStore — 檔案持久化
+│   ├── callbacks.ts          # 回呼事件 — 25 種事件、AES 解密、SHA1 簽名驗證
+│   ├── groups.ts             # 羣組 API（含解散 4.28.6）
+│   ├── todos.ts              # 統一待辦
+│   ├── calendars.ts          # 日曆日程
+│   ├── reminders.ts          # 加急提醒 (4.6.14)
+│   ├── chats.ts              # 聊天讀取 (4.24 MCP)
+│   └── users.ts              # 使用者資訊
+├── tests/                    # 單元測試
+├── package.json
+├── tsconfig.json
+├── jest.config.js
+├── LICENSE
+└── README*.md                # 5 種語言 README
+```
+
+## 開發
+
+```bash
+npm install
+npm run build    # 編譯 TypeScript → dist/
+npm test         # 執行 Jest 測試
+npm run lint     # 僅類型檢查 (tsc --noEmit)
+```
+
+## 授權
+
+MIT — 見 [LICENSE](LICENSE)。

package/dist/accountMessages.d.ts

@@ -0,0 +1,12 @@
+import { LansengerConfig } from "./config";
+import { FetchFn } from "./http";
+import { AccountMessageResult } from "./models";
+export declare function sendAccountMessage(config: LansengerConfig, appToken: string, msgType: string, msgData: Record<string, any>, opts?: {
+    chat_ids?: string[];
+    department_ids?: string[];
+    account_id?: string;
+    entry_id?: string;
+    attach?: string;
+    user_token?: string;
+    fetchFn?: FetchFn;
+}): Promise<AccountMessageResult>;

package/dist/accountMessages.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendAccountMessage = sendAccountMessage;
+const urlHelpers_1 = require("./urlHelpers");
+const http_1 = require("./http");
+const models_1 = require("./models");
+async function sendAccountMessage(config, appToken, msgType, msgData, opts) {
+    if (!msgType)
+        return new models_1.AccountMessageResult({ success: false, error: "msg_type is required" });
+    if (!opts?.chat_ids && !opts?.department_ids)
+        return new models_1.AccountMessageResult({ success: false, error: "at least one of chat_ids or department_ids is required" });
+    if (!msgData)
+        return new models_1.AccountMessageResult({ success: false, error: "msg_data is required" });
+    const userToken = opts?.user_token || "";
+    const url = (0, urlHelpers_1.buildApiUrl)(config, "account_message", "create", appToken, { userToken });
+    const payload = {
+        userIdList: opts?.chat_ids || [], departmentIdList: opts?.department_ids || [],
+        msgType, msgData,
+    };
+    if (opts?.account_id)
+        payload.accountId = opts.account_id;
+    if (opts?.entry_id)
+        payload.entryId = opts.entry_id;
+    if (opts?.attach)
+        payload.attach = opts.attach;
+    const [data, httpErr] = await (0, http_1.doPost)(url, payload, opts?.fetchFn);
+    if (httpErr)
+        return new models_1.AccountMessageResult({ success: false, error: httpErr });
+    const errCode = data.errCode ?? -1;
+    if (errCode !== 0) {
+        const msg = data.errMsg || "Unknown error";
+        return new models_1.AccountMessageResult({ success: false, error: `API error (errCode=${errCode}): ${msg}` });
+    }
+    const d = data.data || {};
+    return new models_1.AccountMessageResult({
+        success: true, message_id: d.msgId,
+        invalid_staff: d.invalidStaff, invalid_department: d.invalidDepartment,
+        raw_response: data,
+    });
+}
+//# sourceMappingURL=accountMessages.js.map

package/dist/auth.d.ts

@@ -0,0 +1,13 @@
+import { LansengerConfig } from "./config";
+import { FetchFn } from "./http";
+import { CredentialStore } from "./persistence";
+export declare class TokenManager {
+    private config;
+    private fetchFn;
+    private token;
+    private tokenExpiry;
+    private store;
+    constructor(config: LansengerConfig, fetchFn: FetchFn, store?: CredentialStore | null);
+    getToken(): Promise<string>;
+    invalidate(): void;
+}

package/dist/auth.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenManager = void 0;
+const constants_1 = require("./constants");
+const exceptions_1 = require("./exceptions");
+const TOKEN_REFRESH_MARGIN = 300;
+class TokenManager {
+    constructor(config, fetchFn, store) {
+        this.token = null;
+        this.tokenExpiry = 0;
+        this.config = config;
+        this.fetchFn = fetchFn;
+        this.store = store || null;
+        if (this.store) {
+            const cached = this.store.loadAppToken();
+            if (cached) {
+                this.token = cached;
+                const state = this.store.load();
+                this.tokenExpiry = state.app_token_expiry || 0;
+            }
+        }
+    }
+    async getToken() {
+        const now = Math.floor(Date.now() / 1000);
+        if (this.token && now < this.tokenExpiry) {
+            return this.token;
+        }
+        const url = `${this.config.api_gateway_url}${constants_1.API_ENDPOINTS.app_token.create}`;
+        const params = new URLSearchParams({
+            grant_type: "client_credential",
+            appid: this.config.app_id,
+            secret: this.config.app_secret,
+        });
+        const fullUrl = `${url}?${params.toString()}`;
+        try {
+            const response = await this.fetchFn(fullUrl);
+            if (!response.ok) {
+                throw new exceptions_1.LansengerNetworkError(`Token request failed: HTTP ${response.status}`);
+            }
+            const data = await response.json();
+            const errCode = data.errCode ?? -1;
+            if (errCode !== 0) {
+                const msg = data.errMsg || "Unknown token error";
+                throw new exceptions_1.LansengerAuthError(`Token error (errCode=${errCode}): ${msg}`, errCode);
+            }
+            const tokenData = data.data || {};
+            this.token = tokenData.appToken;
+            const expiresIn = tokenData.expiresIn || 7200;
+            this.tokenExpiry = Math.floor(Date.now() / 1000) + expiresIn - TOKEN_REFRESH_MARGIN;
+            if (!this.token) {
+                throw new exceptions_1.LansengerAuthError("Token response missing appToken field");
+            }
+            if (this.store) {
+                this.store.saveAppToken(this.token, expiresIn, TOKEN_REFRESH_MARGIN);
+            }
+            return this.token;
+        }
+        catch (e) {
+            if (e instanceof exceptions_1.LansengerAuthError || e instanceof exceptions_1.LansengerNetworkError)
+                throw e;
+            throw new exceptions_1.LansengerNetworkError(`Token request failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    invalidate() {
+        this.token = null;
+        this.tokenExpiry = 0;
+    }
+}
+exports.TokenManager = TokenManager;
+//# sourceMappingURL=auth.js.map