NttuAPI

高效的 NTTU 網路學園 3.0 自動化整合套件，內建圖形驗證碼辨識、登入階段維持、以及通用的課程與首頁資料抓取機制，適合做為其他專案的底層資料來源。

注意:本專案部分代碼使用Gemini3.1編寫

安裝

npm install nttuapi

快速使用

登入與確認狀態

import { NttuAPI } from "nttuapi";

async function main() {
  const api = new NttuAPI();

  // 登入系統 (會自動解析圖形驗證碼並處理重複登入的問題)
  const loginResult = await api.login("您的帳號", "您的密碼");
  console.log("Login Status:", loginResult);

  // 確認目前的連線階段是否有效
  const isActive = await api.checkSession();
  console.log("Session Active:", isActive);
}
main();

主要特性

• 圖形驗證碼自動解析：整合 tesseract.js，自動重試機制大幅提升登入成功率。
• 多重登入迴避：自動處理「此帳號已在其他位置登入」的提示，無縫維持登入階段。
• 完整的 Cookie 與階段管理：底層整合 axios-cookiejar-support 與 tough-cookie。
• 課程抓取：快速提取使用者已選修的所有課程。
• 泛用型資料擷取：通用方法支援抓取儀表板與特定課程內的各類模組清單。
• 自動化內文與附件提取：針對各類詳細頁面，自動過濾並提取純淨的 HTML 內容與附加檔案。

核心方法文件

認證與狀態管理

login(account, password)

自動處理 /secimg.php 驗證碼與 /index/login 流程。若遇驗證碼錯誤將自動重試（預設最高 10 次）。

checkSession()

回傳 boolean，發送請求至儀表板以驗證目前的 Cookie 是否仍然有效。

logout()

結束目前的登入階段並清空本地 Cookie。

課程與資料抓取

getCourseList()

回傳使用者的所有選修課程。

• 回傳型別：Promise<Course[]>
  • id: 系統課程代碼
  • title: 課程名稱
  • teachers: 教師陣列
  • period: 課程期間
  • code: 選課代碼

getDashboardList(type)

抓取儀表板上的系統資訊。

• 支援類型：latestEvent (最近事件), latestBulletin (最新公告), latestDiscuss (最新討論), latestMaterial (最新教材)
• 回傳型別：Promise<ListItem[]>
  • title: 項目標題
  • url: 詳細內容網址
  • columns: 列表上的所有額外欄位資訊

getCourseListItems(courseId, type)

抓取特定課程內的各種模組清單。

• 支援類型：bulletin (公告), homeworkList (作業), examList (測驗), questionnaireList (問卷), latestEvent (最近事件)
• 回傳型別：Promise<ListItem[]>

getItemDetail(url)

輸入由上述 List 方法獲得的 url，提取該項目的詳細文字說明與夾帶附件。

• 回傳型別：Promise<ItemDetail>
  • title: 項目標題
  • contentHtml: 過濾掉頁尾與側邊欄後的純淨 HTML 內容
  • attachments: 陣列，包含 { name: string, url: string }

依賴模組

• axios: 用於 HTTP 請求
• axios-cookiejar-support / tough-cookie: 用於維持連線階段
• cheerio: 用於 HTML 結構解析與資料擷取
• tesseract.js: 用於光學字元辨識 (OCR) 處理圖形驗證碼

授權條款 (License)

本專案採用 Apache License 2.0 授權。 詳細條款請參閱目錄中的 LICENSE 檔案。

Copyright (c) 2026

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.