w-dispatch-ai 1.0.22 → 1.0.23

package/src/quota/toQuotaResult.mjs

@@ -0,0 +1,142 @@
+import get from 'lodash-es/get.js'
+import isestr from 'wsemi/src/isestr.mjs'
+import isearr from 'wsemi/src/isearr.mjs'
+
+
+// toQuotaResult.mjs — 將各家額度查詢結果正規化為統一結構, 並判定帳號是否相符
+//
+// 【email在此類查詢中的真實角色】三家訂閱額度皆綁定「本機該CLI當前登入之憑證」，
+//   無任一家提供「給email即可查任意帳號額度」之公開介面(那將是帳號列舉漏洞)。
+//   故email之作用為比對——查出本機實際登入者，與呼叫端指定之email核對，
+//   相符才視為查到「該帳號」之額度。此設計於一機多帳號(實測本機claude/codex/agy
+//   分屬不同gmail)之情境尤其必要，否則呼叫端會把甲帳號的額度當成乙帳號的。
+//
+// 【為何不符時仍回傳額度資料】資料已取得，丟棄只是浪費一次往返；
+//   但ok一律為false且matched為false，令呼叫端不會誤把他人額度當成指定帳號之額度。
+//
+// 【source欄位】各轉接器可能有主路徑與備援(例如codex以app-server為主、HTTP為備援)，
+//   同一供應商回來的資料可能來自不同介面，呼叫端排錯時須知道走了哪條，故獨立一欄記錄。
+
+
+/**
+ * 將各家額度查詢結果正規化為統一結構，並判定帳號是否相符
+ *
+ * 帳號比對採去空白且不分大小寫之比較，因email本地部分雖理論上區分大小寫，
+ * 但三家供應商實務上皆以不分大小寫視為同一帳號；
+ * 未指定email時不做比對，matched為null，ok僅取決於查詢本身是否成功
+ *
+ * @param {String} provider 輸入供應商種類字串，例如'claude'、'codex'、'antigravity'
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.email=''] 輸入本機該CLI實際登入之帳號email字串，預設''代表無從取得
+ * @param {String} [opt.emailWant=''] 輸入呼叫端指定欲查詢之帳號email字串，預設''代表不比對
+ * @param {String} [opt.plan=''] 輸入方案別字串，例如'max'、'plus'，預設''
+ * @param {String} [opt.planTier=''] 輸入方案細部級距字串，例如'default_claude_max_20x'，預設''
+ * @param {String} [opt.source=''] 輸入資料來源介面字串，例如'oauth-usage-api'、'codex-app-server'、'agy-print'，預設''
+ * @param {Array} [opt.windows=[]] 輸入額度窗口物件陣列，預設[]
+ * @param {Object} [opt.credits=null] 輸入額外用量或點數資訊物件，預設null代表該供應商無此概念或未啟用
+ * @param {Object} [opt.raw=null] 輸入供應商原始回應物件，預設null
+ * @param {String} [opt.error=''] 輸入錯誤訊息字串，預設''代表查詢成功
+ * @param {String} [opt.errorType=''] 輸入機器可讀之錯誤類別字串，預設''
+ * @param {Number} [opt.durationMs=0] 輸入耗時毫秒，預設0
+ * @returns {Object} 回傳結果物件，內含ok(查詢成功且帳號相符布林值)、provider、email(本機實際登入帳號)、matched(帳號是否相符布林值，未指定email時為null)、plan、planTier、source、windows(窗口陣列)、credits、raw、error、errorType、durationMs
+ * @example
+ *
+ * import toQuotaResult from './src/quota/toQuotaResult.mjs'
+ *
+ * let r = toQuotaResult('claude', { email: 'a@b.com', emailWant: 'c@d.com' })
+ * console.log(r.ok, r.matched)
+ * // => false false
+ *
+ */
+function toQuotaResult(provider, opt = {}) {
+
+    //provider
+    if (!isestr(provider)) {
+        provider = ''
+    }
+
+    //email, 本機該CLI實際登入之帳號
+    let email = get(opt, 'email', '')
+    if (!isestr(email)) {
+        email = ''
+    }
+
+    //emailWant, 呼叫端指定欲查詢之帳號
+    let emailWant = get(opt, 'emailWant', '')
+    if (!isestr(emailWant)) {
+        emailWant = ''
+    }
+
+    //error
+    let error = get(opt, 'error', '')
+    if (!isestr(error)) {
+        error = ''
+    }
+
+    //errorType
+    let errorType = get(opt, 'errorType', '')
+    if (!isestr(errorType)) {
+        errorType = ''
+    }
+
+    //matched, 未指定emailWant時不比對(null); 指定但無從取得本機帳號時視為不符並補述原因
+    let matched = null
+    if (emailWant !== '') {
+        if (email === '') {
+            matched = false
+            if (error === '') {
+                error = `cannot determine the local ${provider} login account, so it is unknown whether it is the requested account [${emailWant}]`
+                errorType = 'account'
+            }
+        }
+        else {
+            matched = email.trim().toLowerCase() === emailWant.trim().toLowerCase()
+            if (!matched && error === '') {
+                error = `local ${provider} login account is [${email}], which does not match the requested account [${emailWant}]`
+                errorType = 'account'
+            }
+        }
+    }
+
+    //windows
+    let windows = get(opt, 'windows', null)
+    if (!isearr(windows)) {
+        windows = []
+    }
+
+    //plan與planTier與source
+    let plan = get(opt, 'plan', '')
+    if (!isestr(plan)) {
+        plan = ''
+    }
+    let planTier = get(opt, 'planTier', '')
+    if (!isestr(planTier)) {
+        planTier = ''
+    }
+    let source = get(opt, 'source', '')
+    if (!isestr(source)) {
+        source = ''
+    }
+
+    //ok, 須查詢無誤且帳號相符(未指定email時視為相符)
+    let ok = error === '' && matched !== false
+
+    return {
+        ok,
+        provider,
+        email,
+        matched,
+        plan,
+        planTier,
+        source,
+        windows,
+        credits: get(opt, 'credits', null),
+        raw: get(opt, 'raw', null),
+        error,
+        errorType,
+        durationMs: get(opt, 'durationMs', 0),
+    }
+}
+
+
+export default toQuotaResult

package/src/quota/toQuotaScopedLabel.mjs

@@ -0,0 +1,45 @@
+import isestr from 'wsemi/src/isestr.mjs'
+import toQuotaLabel from './toQuotaLabel.mjs'
+
+
+// toQuotaScopedLabel.mjs — 組出帶適用範圍之額度窗口標籤(單一來源)
+//
+// 【為何獨立成檔】三個額度轉接器都要把「窗口長度」與「範圍」拼成「7天(Fable)」「5小時(Gemini Models)」
+//   這類標籤, 同一段拼接規則曾於fromCodexUsageHttp/getQuotaClaude/getQuotaCodex各手寫一份——
+//   依全域規範「同一規則手寫≥2處即補丁訊號」收斂於此。基底一律取自toQuotaLabel,
+//   窗口長度變動時標籤自動跟著正確, 不得手寫「7天」字串。
+
+
+/**
+ * 組出帶適用範圍之額度窗口標籤
+ *
+ * 無範圍時回傳空字串，令toQuotaWindow自行由windowSeconds推導預設標籤；
+ * 有範圍但窗口秒數無效(供應商未提供)時僅以範圍為標籤
+ *
+ * @param {Number} windowSeconds 輸入窗口長度秒數
+ * @param {String} scope 輸入適用範圍字串，例如模型名或群組名
+ * @returns {String} 回傳標籤字串，例如'7天(Fable)'；無範圍回傳''
+ * @example
+ *
+ * import toQuotaScopedLabel from './src/quota/toQuotaScopedLabel.mjs'
+ *
+ * console.log(toQuotaScopedLabel(604800, 'Fable'))
+ * // => 7天(Fable)
+ *
+ * console.log(toQuotaScopedLabel(null, 'codex-spark'))
+ * // => codex-spark
+ *
+ * console.log(toQuotaScopedLabel(18000, ''))
+ * // => (空字串)
+ *
+ */
+function toQuotaScopedLabel(windowSeconds, scope) {
+    if (!isestr(scope)) {
+        return ''
+    }
+    let base = toQuotaLabel(windowSeconds)
+    return base === '' ? scope : `${base}(${scope})`
+}
+
+
+export default toQuotaScopedLabel

package/src/quota/toQuotaWindow.mjs

@@ -0,0 +1,167 @@
+import get from 'lodash-es/get.js'
+import isnum from 'wsemi/src/isnum.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import isbol from 'wsemi/src/isbol.mjs'
+import cdbl from 'wsemi/src/cdbl.mjs'
+import toQuotaLabel from './toQuotaLabel.mjs'
+
+
+// toQuotaWindow.mjs — 將各家額度窗口正規化為統一結構
+//
+// 【為何要正規化】三家回傳形狀互異：Claude給utilization(已用百分比)與ISO字串resets_at，
+//   Codex給usedPercent與unix秒數resetsAt外加windowDurationMins，
+//   Antigravity給remaining_fraction(剩餘比例)與ISO字串reset_time；
+//   呼叫端若直接吃原始形狀，每加一家就要改一次判斷。統一於此後，
+//   呼叫端只認一組欄位，各家差異收斂在各自的轉接器內。
+//
+// 【為何同時給resetAt與resetAfterSeconds】前者適合顯示絕對時間，後者適合倒數與排程判斷；
+//   兩者能互推，故任一有值即補算另一，令呼叫端不必自行換算。
+//
+// 【label由誰決定】未給label時由windowSeconds經toQuotaLabel推導；轉接器需要帶範圍之標籤
+//   (如「7天(Fable)」)時, 亦應以toQuotaLabel取基底再拼接, 不得手寫「7天」字串。
+//
+// 【key是供應商原生識別, 刻意不統一; 跨家比較用windowSeconds+scope】統一的是信封(上列欄位),
+//   key則原樣透傳各家自己的窗口識別——Claude為limits[].kind(session/weekly_all/weekly_scoped;
+//   回退舊欄位時為five_hour/seven_day_opus等欄位名)、Codex為rateLimits之primary/secondary物件名、
+//   agy為buckets[].id(gemini-5h/gemini-weekly/3p-5h/3p-weekly); 僅巢狀限額需組唯一鍵時
+//   由轉接器以「<識別>:primary|secondary」複合(如code_review:primary)。保留原生值可回溯raw,
+//   也不必為求一致把agy之4桶2群組硬壓成2個。故呼叫端要「跨家找5小時窗口」請以
+//   windowSeconds===18000(7天為604800)配scope判斷, 不得比對key字串。
+
+
+/**
+ * 將各家額度窗口正規化為統一結構
+ *
+ * resetAt可給ISO字串或unix秒數(整數)，一律轉為ISO字串；
+ * resetAt與resetAfterSeconds任一有值即自動補算另一；
+ * usedPercent夾至0~100，remainingPercent由其推得，未知時兩者皆為null(不假造100)；
+ * label未給時由windowSeconds推導，故供應商調整窗口長度時標籤自動跟著正確
+ *
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.key=''] 輸入窗口之機器可讀鍵字串，為供應商原生識別原樣透傳(Claude之limits[].kind如'session'、Codex之'primary'/'secondary'、agy之buckets[].id如'gemini-5h')，各家不同且刻意不統一；跨家比較請用windowSeconds配scope而非key，預設''
+ * @param {String} [opt.label=''] 輸入窗口之人類可讀標籤字串，預設''代表由windowSeconds推導
+ * @param {Number} [opt.windowSeconds=null] 輸入窗口長度秒數，預設null代表供應商未提供
+ * @param {Number} [opt.usedPercent=null] 輸入已用百分比數值(0~100)，預設null代表未知
+ * @param {String|Number} [opt.resetAt=''] 輸入窗口重置時刻，可為ISO字串或unix秒數整數，預設''
+ * @param {Number} [opt.resetAfterSeconds=null] 輸入距重置之剩餘秒數，預設null代表由resetAt推算
+ * @param {String} [opt.scope=''] 輸入窗口適用範圍字串，例如模型名稱或群組名稱，預設''代表全域
+ * @param {Boolean} [opt.active=false] 輸入是否為當前生效(最先觸頂)窗口布林值，預設false
+ * @param {String} [opt.severity=''] 輸入嚴重度字串，例如'normal'、'warning'、'exhausted'，預設''代表由usedPercent推導(用罄為'exhausted'、其餘'normal'、usedPercent未知則'')
+ * @returns {Object} 回傳窗口物件，內含key(供應商原生識別，各家不同)、label、windowSeconds(跨家比較之正規化維度：18000＝5小時、604800＝7天)、usedPercent、remainingPercent、resetAt(ISO字串)、resetAfterSeconds、scope、active、severity
+ * @example
+ *
+ * import toQuotaWindow from './src/quota/toQuotaWindow.mjs'
+ *
+ * let w = toQuotaWindow({ key: 'five_hour', windowSeconds: 18000, usedPercent: 11 })
+ * console.log(w.label, w.remainingPercent)
+ * // => 5小時 89
+ *
+ */
+function toQuotaWindow(opt = {}) {
+
+    //key
+    let key = get(opt, 'key', '')
+    if (!isestr(key)) {
+        key = ''
+    }
+
+    //windowSeconds, 無效視為供應商未提供
+    let windowSeconds = get(opt, 'windowSeconds', null)
+    if (!isnum(windowSeconds)) {
+        windowSeconds = null
+    }
+    else {
+        windowSeconds = cdbl(windowSeconds)
+    }
+
+    //label, 未給時由windowSeconds推導
+    let label = get(opt, 'label', '')
+    if (!isestr(label)) {
+        label = toQuotaLabel(windowSeconds)
+    }
+
+    //usedPercent, 無效視為未知; 有效則夾至0~100避免供應商回傳越界值污染剩餘量
+    let usedPercent = get(opt, 'usedPercent', null)
+    if (!isnum(usedPercent)) {
+        usedPercent = null
+    }
+    else {
+        usedPercent = Math.min(100, Math.max(0, cdbl(usedPercent)))
+    }
+
+    //remainingPercent, 由usedPercent推得, 未知時同為未知
+    let remainingPercent = null
+    if (usedPercent !== null) {
+        remainingPercent = Math.round((100 - usedPercent) * 100) / 100
+    }
+
+    //resetAt, 接受ISO字串或unix秒數, 一律轉ISO字串
+    let resetAt = get(opt, 'resetAt', '')
+    if (isnum(resetAt) && cdbl(resetAt) > 0) {
+        resetAt = new Date(cdbl(resetAt) * 1000).toISOString()
+    }
+    else if (isestr(resetAt)) {
+        let d = new Date(resetAt)
+        resetAt = isNaN(d.getTime()) ? '' : d.toISOString()
+    }
+    else {
+        resetAt = ''
+    }
+
+    //resetAfterSeconds, 無效時由resetAt推算, 令呼叫端不論供應商給哪一種都拿得到倒數
+    let resetAfterSeconds = get(opt, 'resetAfterSeconds', null)
+    if (!isnum(resetAfterSeconds)) {
+        resetAfterSeconds = null
+        if (resetAt !== '') {
+            let dt = Math.round((new Date(resetAt).getTime() - Date.now()) / 1000)
+            resetAfterSeconds = Math.max(0, dt)
+        }
+    }
+    else {
+        resetAfterSeconds = Math.max(0, Math.round(cdbl(resetAfterSeconds)))
+    }
+
+    //resetAt, 供應商只給倒數秒數時反推絕對時刻
+    if (resetAt === '' && resetAfterSeconds !== null) {
+        resetAt = new Date(Date.now() + resetAfterSeconds * 1000).toISOString()
+    }
+
+    //scope, 例如僅適用某模型或某群組之窗口
+    let scope = get(opt, 'scope', '')
+    if (!isestr(scope)) {
+        scope = ''
+    }
+
+    //active
+    let active = get(opt, 'active', null)
+    if (!isbol(active)) {
+        active = false
+    }
+
+    //severity, 供應商有給(如Claude之limits[].severity)即用之; 未給則由usedPercent推導——
+    //用罄為'exhausted'、其餘'normal'、usedPercent未知則''。三家對稱: 曾因codex路徑未給而為空字串,
+    //與claude/agy之'normal'不對稱, 呼叫端得分家判斷; 收斂於此後任一家未給皆有一致預設
+    let severity = get(opt, 'severity', '')
+    if (!isestr(severity)) {
+        severity = ''
+        if (usedPercent !== null) {
+            severity = usedPercent >= 100 ? 'exhausted' : 'normal'
+        }
+    }
+
+    return {
+        key,
+        label,
+        windowSeconds,
+        usedPercent,
+        remainingPercent,
+        resetAt,
+        resetAfterSeconds,
+        scope,
+        active,
+        severity,
+    }
+}
+
+
+export default toQuotaWindow

package/test/tools/fakeCliForTest.mjs

@@ -81,9 +81,10 @@ process.stdin.on('end', () => {
  * 產生一支測試用的假CLI，回傳其執行檔路徑與清除函數
  *
  * @param {String} name 輸入假CLI名稱字串，各測試檔須給予不同名稱，避免mocha並行執行時互相干擾
+ * @param {String} [entryCode=CODE_ENTRY] 輸入假CLI之node腳本原始碼字串，預設為回聲args/stdin/env之腳本；需模擬特定協定(如codex app-server之JSON-RPC、agy之--version與-p /usage)時自訂
  * @returns {Object} 回傳物件，內含exe(假CLI執行檔絕對路徑字串)、fd(產物資料夾絕對路徑字串)、clean(清除產物之函數)
  */
-function createFakeCli(name) {
+function createFakeCli(name, entryCode = CODE_ENTRY) {
 
     //fd, 印出absolute路徑供除錯驗收
     let fd = path.resolve(FD_BASE, name)
@@ -92,9 +93,9 @@ function createFakeCli(name) {
     let fdEntry = path.join(fd, 'node_modules', name)
     fs.mkdirSync(fdEntry, { recursive: true })
 
-    //entry
+    //entry, 預設回聲腳本或呼叫端自訂之協定模擬腳本
     let fpEntry = path.join(fdEntry, 'entry.mjs')
-    fs.writeFileSync(fpEntry, CODE_ENTRY, 'utf8')
+    fs.writeFileSync(fpEntry, typeof entryCode === 'string' && entryCode !== '' ? entryCode : CODE_ENTRY, 'utf8')
 
     //exe
     let exe = ''

package/test/tools/fakeServerForQuotaTest.mjs

@@ -0,0 +1,171 @@
+import http from 'http'
+
+
+// fakeServerForQuotaTest.mjs — 額度查詢用之假HTTP伺服器
+//
+// 三個額度轉接器之REST路徑分別打Anthropic之/api/oauth/usage(+/profile)與chatgpt.com之
+// /backend-api/wham/usage; 其可觀察行為為「送了什麼標頭、如何處理各種狀態碼與回應形狀」,
+// 故起本機伺服器依路徑與Authorization權杖決定回應, 令getQuotaClaude/getQuotaCodex/fetchQuotaJson
+// 可離線逐條斷言, 不依賴真帳號與網路。回應fixture形狀取自2026-09-05本機實測之真實回應。
+//
+// 【行為路由(依Bearer權杖)】對所有路徑一致:
+//   tok-ok        — 200, 依路徑回對應fixture
+//   tok-401       — 401 {error:{type:'authentication_error'}}
+//   tok-403-org   — 403, 本文含oauth_not_allowed_for_organization
+//   tok-429       — 429
+//   tok-500       — 500
+//   tok-notjson   — 200但本體非JSON
+//   tok-slow      — 延遲10秒(逾時路徑用)
+//   tok-big       — 200但本體約2MB(toolarge路徑用)
+//   tok-echo      — 200, 回{ headers }(斷言送出之標頭用)
+//   tok-legacy    — 200, claude usage僅有頂層舊欄位(無limits[], 回退路徑用)
+//   其他/無權杖   — 401
+
+
+//claude之/api/oauth/usage回應fixture(新結構limits[]+頂層舊欄位並存, 實測形狀)
+let FIXTURE_CLAUDE_USAGE = {
+    five_hour: { utilization: 3, resets_at: '2099-01-01T05:00:00.000Z' },
+    seven_day: { utilization: 13, resets_at: '2099-01-03T00:00:00.000Z' },
+    seven_day_opus: { utilization: 0, resets_at: '2099-01-03T00:00:00.000Z' },
+    limits: [
+        { kind: 'session', group: 'session', percent: 3, severity: 'normal', resets_at: '2099-01-01T05:00:00.000Z', scope: null, is_active: false },
+        { kind: 'weekly_all', group: 'weekly', percent: 13, severity: 'normal', resets_at: '2099-01-03T00:00:00.000Z', scope: null, is_active: false },
+        { kind: 'weekly_scoped', group: 'weekly', percent: 15, severity: 'normal', resets_at: '2099-01-03T00:00:00.000Z', scope: { model: { display_name: 'Fable' }, surface: null }, is_active: true },
+    ],
+    extra_usage: { is_enabled: false, monthly_limit: null, used_credits: null, utilization: null },
+    spend: { used: { amount_minor: 0, currency: 'USD' }, percent: 0 },
+}
+
+
+//claude之/api/oauth/usage僅頂層舊欄位之fixture(回退路徑用)
+let FIXTURE_CLAUDE_USAGE_LEGACY = {
+    five_hour: { utilization: 42, resets_at: '2099-01-01T05:00:00.000Z' },
+    seven_day: { utilization: 7, resets_at: '2099-01-03T00:00:00.000Z' },
+    seven_day_sonnet: { utilization: 1, resets_at: '2099-01-03T00:00:00.000Z' },
+}
+
+
+//claude之/api/oauth/profile回應fixture
+let FIXTURE_CLAUDE_PROFILE = {
+    account: { email: 'profile-user@example.com', full_name: 'Profile User' },
+}
+
+
+//codex之/backend-api/wham/usage回應fixture(實測形狀, additional_rate_limits取自同類工具fixture)
+let FIXTURE_CODEX_USAGE = {
+    email: 'codex-user@example.com',
+    plan_type: 'plus',
+    rate_limit: {
+        primary_window: { used_percent: 0, limit_window_seconds: 18000, reset_after_seconds: 17999, reset_at: 4102444800 },
+        secondary_window: { used_percent: 31, limit_window_seconds: 604800, reset_after_seconds: 501107, reset_at: 4102444800 },
+    },
+    code_review_rate_limit: {
+        primary_window: { used_percent: 5, limit_window_seconds: 18000, reset_after_seconds: 1000 },
+    },
+    additional_rate_limits: [
+        { limit_name: 'codex-spark', display_name: 'GPT-5.3-Codex-Spark', primary_window: { used_percent: 12, limit_window_seconds: 18000, reset_after_seconds: 500 } },
+    ],
+    credits: { has_credits: false, unlimited: false, balance: '0' },
+    rate_limit_reset_credits: { available_count: 1 },
+    spend_control: { reached: false, individual_limit: null },
+    rate_limit_reached_type: null,
+}
+
+
+/**
+ * 啟動額度查詢用之假HTTP伺服器
+ *
+ * @returns {Promise} 回傳Promise，resolve回傳物件，內含port(埠號)、url(基底網址字串，如http://127.0.0.1:PORT)、usageUrlClaude、profileUrlClaude、usageUrlCodex(三個端點完整網址)、close(關閉伺服器之async函數)
+ */
+async function fakeServerForQuotaTest() {
+
+    //sockets, 追蹤連線供close時強制斷開(避免keep-alive令close懸置)
+    let sockets = new Set()
+
+    let server = http.createServer((req, res) => {
+
+        let auth = req.headers['authorization'] || ''
+        let tok = auth.replace(/^Bearer\s+/i, '')
+        let send = (code, obj) => {
+            res.writeHead(code, { 'Content-Type': 'application/json' })
+            res.end(JSON.stringify(obj))
+        }
+
+        //權杖行為
+        if (tok === 'tok-401' || tok === '') {
+            return send(401, { type: 'error', error: { type: 'authentication_error', message: 'OAuth token has expired.' } })
+        }
+        if (tok === 'tok-403-org') {
+            return send(403, { type: 'error', error: { type: 'permission_error', message: 'oauth_not_allowed_for_organization' } })
+        }
+        if (tok === 'tok-429') {
+            return send(429, { type: 'error', error: { type: 'rate_limit_error', message: 'Too many requests' } })
+        }
+        if (tok === 'tok-500') {
+            return send(500, { type: 'error', error: { type: 'api_error', message: 'internal' } })
+        }
+        if (tok === 'tok-notjson') {
+            res.writeHead(200, { 'Content-Type': 'text/plain' })
+            return res.end('<html>not json</html>')
+        }
+        if (tok === 'tok-slow') {
+            return setTimeout(() => send(200, FIXTURE_CLAUDE_USAGE), 10000)
+        }
+        if (tok === 'tok-big') {
+            res.writeHead(200, { 'Content-Type': 'application/json' })
+            return res.end(JSON.stringify({ pad: 'x'.repeat(2 * 1024 * 1024) }))
+        }
+        if (tok === 'tok-echo') {
+            return send(200, { headers: req.headers })
+        }
+        if (tok !== 'tok-ok' && tok !== 'tok-legacy') {
+            return send(401, { type: 'error', error: { type: 'authentication_error', message: 'Invalid token' } })
+        }
+
+        //路徑fixture
+        if (req.url.endsWith('/api/oauth/usage')) {
+            return send(200, tok === 'tok-legacy' ? FIXTURE_CLAUDE_USAGE_LEGACY : FIXTURE_CLAUDE_USAGE)
+        }
+        if (req.url.endsWith('/api/oauth/profile')) {
+            return send(200, FIXTURE_CLAUDE_PROFILE)
+        }
+        if (req.url.endsWith('/backend-api/wham/usage')) {
+            return send(200, FIXTURE_CODEX_USAGE)
+        }
+        return send(404, { error: { message: 'not found' } })
+    })
+
+    server.on('connection', (s) => {
+        sockets.add(s)
+        s.on('close', () => sockets.delete(s))
+    })
+
+    //listen於127.0.0.1動態埠
+    await new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', resolve)
+    })
+    let port = server.address().port
+    let url = `http://127.0.0.1:${port}`
+
+    let close = async () => {
+        for (let s of sockets) {
+            s.destroy()
+        }
+        await new Promise((resolve) => {
+            server.close(resolve)
+        })
+    }
+
+    return {
+        port,
+        url,
+        usageUrlClaude: `${url}/api/oauth/usage`,
+        profileUrlClaude: `${url}/api/oauth/profile`,
+        usageUrlCodex: `${url}/backend-api/wham/usage`,
+        close,
+    }
+}
+
+
+export default fakeServerForQuotaTest
+export { FIXTURE_CLAUDE_USAGE, FIXTURE_CLAUDE_USAGE_LEGACY, FIXTURE_CLAUDE_PROFILE, FIXTURE_CODEX_USAGE }

package/test/unit-WDispatchAi.test.mjs

@@ -13,6 +13,9 @@ import dispatchApiOpenaiCompat from '../src/dispatchApiOpenaiCompat.mjs'
 import dispatchApiOpenaiResponses from '../src/dispatchApiOpenaiResponses.mjs'
 import providers from '../src/providers.mjs'
 import resolveProviders from '../src/resolveProviders.mjs'
+import getQuotaClaude from '../src/quota/getQuotaClaude.mjs'
+import getQuotaCodex from '../src/quota/getQuotaCodex.mjs'
+import getQuotaAntigravity from '../src/quota/getQuotaAntigravity.mjs'
 
 
 describe('WDispatchAi', function() {
@@ -38,6 +41,9 @@ describe('WDispatchAi', function() {
             'createFileStore',
             'createUsageCounter',
             'salvageTruncatedArray',
+            'getQuotaClaude',
+            'getQuotaCodex',
+            'getQuotaAntigravity',
         ]
         assert.strict.deepEqual(r, rr)
     })
@@ -50,7 +56,7 @@ describe('WDispatchAi', function() {
 
     it('各鍵值型別正確(KINDS與providers為物件, NO_SIDE_EFFECT為字串, 其餘為函數)', function() {
         let r = map(keys(wi), (k) => typeof wi[k])
-        let rr = ['object', 'string', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'object', 'function', 'function', 'function', 'function', 'function', 'function']
+        let rr = ['object', 'string', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'object', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function']
         assert.strict.deepEqual(r, rr)
     })
 
@@ -67,8 +73,11 @@ describe('WDispatchAi', function() {
             wi.dispatchApiOpenaiResponses === dispatchApiOpenaiResponses,
             wi.providers === providers,
             wi.resolveProviders === resolveProviders,
+            wi.getQuotaClaude === getQuotaClaude,
+            wi.getQuotaCodex === getQuotaCodex,
+            wi.getQuotaAntigravity === getQuotaAntigravity,
         ]
-        let rr = [true, true, true, true, true, true, true, true, true, true, true]
+        let rr = [true, true, true, true, true, true, true, true, true, true, true, true, true, true]
         assert.strict.deepEqual(r, rr)
     })
 

package/test/unit-fetchQuotaJson.test.mjs

@@ -0,0 +1,70 @@
+import assert from 'assert'
+import fetchQuotaJson from '../src/quota/fetchQuotaJson.mjs'
+import fakeServerForQuotaTest from './tools/fakeServerForQuotaTest.mjs'
+
+
+describe('fetchQuotaJson', function() {
+
+    let svr = null
+
+    before(async function() {
+        svr = await fakeServerForQuotaTest()
+    })
+
+    after(async function() {
+        if (svr) {
+            await svr.close()
+        }
+    })
+
+    let call = (tok, o = {}) => fetchQuotaJson(svr.usageUrlClaude, { headers: { Authorization: `Bearer ${tok}` }, ...o })
+
+    it('url無效回params, 不reject', async function() {
+        let r = await fetchQuotaJson('')
+        let rr = [r.ok, r.status, r.data, r.errorType]
+        assert.strict.deepEqual(rr, [false, 0, null, 'params'])
+    })
+
+    it('200且JSON合法時回data; 物件body自動序列化並補Content-Type', async function() {
+        let r1 = await call('tok-ok')
+        let r2 = await fetchQuotaJson(svr.usageUrlClaude, { method: 'POST', headers: { Authorization: 'Bearer tok-echo' }, body: { a: 1 } })
+        let rr = [r1.ok, r1.status, typeof r1.data.limits, r2.ok, r2.data.headers['content-type'], r2.data.headers['content-length']]
+        assert.strict.deepEqual(rr, [true, 200, 'object', true, 'application/json', '7'])
+    })
+
+    it('狀態碼分類: 401→auth, 403→forbidden, 429→ratelimit, 500→http; 錯誤訊息含本文片段', async function() {
+        let r1 = await call('tok-401')
+        let r2 = await call('tok-403-org')
+        let r3 = await call('tok-429')
+        let r4 = await call('tok-500')
+        let rr = [
+            [r1.ok, r1.status, r1.errorType, r1.error.indexOf('unauthorized(401)') === 0],
+            [r2.ok, r2.status, r2.errorType, /oauth_not_allowed_for_organization/.test(r2.error)],
+            [r3.ok, r3.status, r3.errorType],
+            [r4.ok, r4.status, r4.errorType],
+        ]
+        assert.strict.deepEqual(rr, [[false, 401, 'auth', true], [false, 403, 'forbidden', true], [false, 429, 'ratelimit'], [false, 500, 'http']])
+    })
+
+    it('200但非JSON→parse; 本文超過maxBodyBytes→toolarge; 逾時→timeout; 連線拒絕→network', async function() {
+        let r1 = await call('tok-notjson')
+        let r2 = await call('tok-big', { maxBodyBytes: 1024 })
+        let r3 = await call('tok-slow', { timeoutMs: 300 })
+        let r4 = await fetchQuotaJson('http://127.0.0.1:9/nothing', { timeoutMs: 3000 })
+        let rr = [
+            [r1.ok, r1.status, r1.errorType],
+            [r2.ok, r2.errorType, /too large/.test(r2.error)],
+            [r3.ok, r3.status, r3.errorType],
+            [r4.ok, r4.status, r4.errorType],
+        ]
+        assert.strict.deepEqual(rr, [[false, 200, 'parse'], [false, 'toolarge', true], [false, 0, 'timeout'], [false, 0, 'network']])
+    })
+
+    it('redact: 錯誤訊息中之機密值被遮蔽(長度不足6者不處理, 避免誤遮常見短字串)', async function() {
+        //tok-echo會把標頭回顯, 模擬對端把權杖夾進錯誤頁的情境: 以403路徑令本文含權杖字樣
+        let r = await fetchQuotaJson(svr.usageUrlClaude, { headers: { 'Authorization': 'Bearer tok-403-org', 'X-Secret': 'my-secret-value' }, redact: ['oauth_not_allowed_for_organization', 'org'] })
+        let rr = [r.errorType, /\[REDACTED\]/.test(r.error), /oauth_not_allowed_for_organization/.test(r.error), /forbidden\(403\)/.test(r.error)]
+        assert.strict.deepEqual(rr, ['forbidden', true, false, true])
+    })
+
+})