w-dispatch-ai 1.0.21 → 1.0.23

package/src/quota/fetchQuotaJson.mjs

@@ -0,0 +1,276 @@
+import get from 'lodash-es/get.js'
+import isestr from 'wsemi/src/isestr.mjs'
+import iseobj from 'wsemi/src/iseobj.mjs'
+import isearr from 'wsemi/src/isearr.mjs'
+import castPintOr from '../castPintOr.mjs'
+import dfQuotaTimeoutMs from './dfQuotaTimeoutMs.mjs'
+
+
+// fetchQuotaJson.mjs — 各額度查詢端點共用之HTTP請求並解析JSON
+//
+// 【為何自寫而不引HTTP套件】本套件相依僅wsemi一項, 額度查詢只需單次請求,
+//   Node 18+已內建fetch, 引入額外相依不划算。
+//
+// 【為何逾時走AbortController且涵蓋讀取本文】fetch本身無逾時參數; 且fetch resolve只代表收到標頭,
+//   本文仍可能無限期慢流, 故計時器須持續到本文讀完才解除。
+//
+// 【為何錯誤要分類】呼叫端對「token過期(auth)」與「暫時性網路失敗(network/timeout)」
+//   之處置完全不同, 只給錯誤訊息字串則呼叫端須解析文字判斷。
+//
+// 【為何有redact與maxBodyBytes】錯誤訊息會夾帶回應本文片段, 若對端把請求標頭回顯(除錯頁、代理錯誤頁),
+//   權杖或帳號ID便會流入log; 呼叫端把機密值交給redact, 進訊息前一律替換。本文大小上限則防止
+//   異常回應(例如導向到整頁HTML或無限串流)撐爆記憶體; 額度端點正常回應不到10KB, 1MB綽綽有餘。
+//   兩者皆參考同類工具codex-reset-checker之做法。
+
+
+//回應本文預設上限位元組
+let DEFAULT_MAX_BODY_BYTES = 1048576
+
+
+//遮蔽替代文字; 短於此長度之機密值不遮(避免把常見短字串誤遮成無法閱讀)
+let REDACT_MASK = '[REDACTED]'
+let REDACT_MIN_LEN = 6
+
+
+/**
+ * 將文字中之機密值替換為遮蔽字
+ *
+ * @param {String} text 輸入文字
+ * @param {Array} redact 輸入機密值字串陣列
+ * @returns {String} 回傳替換後文字
+ */
+function redactText(text, redact) {
+    let s = String(text)
+    for (let v of redact) {
+        if (isestr(v) && v.length >= REDACT_MIN_LEN) {
+            s = s.split(v).join(REDACT_MASK)
+        }
+    }
+    return s
+}
+
+
+/**
+ * 讀取回應本文, 超過上限即中止
+ *
+ * @param {Object} r 輸入fetch之Response
+ * @param {Number} maxBytes 輸入上限位元組
+ * @returns {Promise} 回傳物件{ok, text, bytes}, 超限時ok為false且bytes為已讀位元組(或content-length)
+ */
+async function readBodyCapped(r, maxBytes) {
+
+    //content-length, 先擋明顯超限者, 不必開始讀
+    let cl = Number(r.headers.get('content-length') || 0)
+    if (cl > maxBytes) {
+        return { ok: false, text: '', bytes: cl }
+    }
+
+    //無串流介面時退回text(), 讀完再量
+    let body = r.body
+    if (!body || typeof body.getReader !== 'function') {
+        let t = await r.text()
+        let n = Buffer.byteLength(t)
+        if (n > maxBytes) {
+            return { ok: false, text: '', bytes: n }
+        }
+        return { ok: true, text: t, bytes: n }
+    }
+
+    //串流讀取, 邊讀邊量, 超限即取消
+    let reader = body.getReader()
+    let chunks = []
+    let total = 0
+    while (true) {
+        let { done, value } = await reader.read()
+        if (done) {
+            break
+        }
+        total += value.byteLength
+        if (total > maxBytes) {
+            try {
+                await reader.cancel()
+            }
+            catch (err) {}
+            return { ok: false, text: '', bytes: total }
+        }
+        chunks.push(Buffer.from(value))
+    }
+    return { ok: true, text: Buffer.concat(chunks).toString('utf8'), bytes: total }
+}
+
+
+/**
+ * 各額度查詢端點共用之HTTP請求並解析JSON
+ *
+ * 本函數不會reject，一律以結果物件之ok與error欄位回報成敗，
+ * 並將失敗歸入機器可讀之errorType，令呼叫端無須解析錯誤訊息字串即可分流處置
+ *
+ * @param {String} url 輸入查詢端點網址字串
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.method='GET'] 輸入HTTP方法字串，預設'GET'
+ * @param {Object|String} [opt.body=null] 輸入請求內容，給物件時序列化為JSON並自動補Content-Type，給字串時原樣送出，預設null代表無內容
+ * @param {Object} [opt.headers={}] 輸入額外HTTP標頭物件，預設{}
+ * @param {Number} [opt.timeoutMs=20000] 輸入逾時毫秒正整數，涵蓋連線至本文讀完，逾時將中止連線，預設20000
+ * @param {Number} [opt.maxBodyBytes=1048576] 輸入回應本文上限位元組正整數，超過即中止並回errorType 'toolarge'，預設1048576
+ * @param {Array} [opt.redact=[]] 輸入須自錯誤訊息中遮蔽之機密值字串陣列(例如權杖、帳號ID)，長度不足6者不處理，預設[]
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、status(HTTP狀態碼整數，未連上為0)、data(解析後之JSON物件，失敗為null)、error(錯誤訊息字串，成功時為空字串，已套用redact)、errorType(錯誤類別字串：params/auth/forbidden/ratelimit/http/parse/timeout/network/toolarge)、durationMs(耗時毫秒)，本函數不會reject
+ * @example
+ * //need network
+ *
+ * import fetchQuotaJson from './src/quota/fetchQuotaJson.mjs'
+ *
+ * let test = async () => {
+ *     let r = await fetchQuotaJson('https://api.anthropic.com/api/oauth/usage', {
+ *         headers: { Authorization: 'Bearer xxx' },
+ *     })
+ *     console.log(r.ok, r.status)
+ *     // => false 401
+ * }
+ * test()
+ *
+ */
+async function fetchQuotaJson(url, opt = {}) {
+
+    let t0 = Date.now()
+
+    //rs, 各分支共用之結果骨架
+    let rs = (ok, status, data, error, errorType) => {
+        return {
+            ok,
+            status,
+            data,
+            error,
+            errorType,
+            durationMs: Date.now() - t0,
+        }
+    }
+
+    //check url
+    if (!isestr(url)) {
+        return rs(false, 0, null, 'url must be a non-empty string', 'params')
+    }
+
+    //headers, 非物件回退空物件
+    let headers = get(opt, 'headers', null)
+    if (!iseobj(headers)) {
+        headers = {}
+    }
+
+    //method, 無效回退GET
+    let method = get(opt, 'method', null)
+    if (!isestr(method)) {
+        method = 'GET'
+    }
+
+    //body, 物件即序列化為JSON並補Content-Type, 字串原樣送出
+    let body = get(opt, 'body', null)
+    if (iseobj(body)) {
+        body = JSON.stringify(body)
+        if (!isestr(get(headers, 'Content-Type', null))) {
+            headers = {
+                ...headers,
+                'Content-Type': 'application/json',
+            }
+        }
+    }
+    else if (!isestr(body)) {
+        body = null
+    }
+
+    //timeoutMs
+    let timeoutMs = castPintOr(get(opt, 'timeoutMs', null), dfQuotaTimeoutMs)
+
+    //maxBodyBytes
+    let maxBodyBytes = castPintOr(get(opt, 'maxBodyBytes', null), DEFAULT_MAX_BODY_BYTES)
+
+    //redact
+    let redact = get(opt, 'redact', null)
+    if (!isearr(redact)) {
+        redact = []
+    }
+
+    //snip, 錯誤訊息用之本文片段: 先遮蔽再截短, 避免機密值被截半後漏出
+    let snip = (text) => redactText(text, redact).slice(0, 300)
+
+    //ac, 逾時中止連線; 計時器持續至本文讀完
+    let ac = new AbortController()
+    let idTimer = setTimeout(() => {
+        ac.abort()
+    }, timeoutMs)
+
+    let r = null
+    let text = ''
+    try {
+
+        //fetch, resolve僅代表收到標頭
+        try {
+            r = await fetch(url, {
+                method,
+                headers,
+                body,
+                signal: ac.signal,
+            })
+        }
+        catch (err) {
+            if (get(err, 'name', '') === 'AbortError') {
+                return rs(false, 0, null, `request timeout over ${timeoutMs}ms`, 'timeout')
+            }
+            return rs(false, 0, null, `network error: ${redactText(get(err, 'message', 'unknown'), redact)}`, 'network')
+        }
+
+        //body, 先取原文再解析, 令非JSON之錯誤頁能原樣回報而非只說解析失敗
+        try {
+            let rb = await readBodyCapped(r, maxBodyBytes)
+            if (!rb.ok) {
+                ac.abort()
+                return rs(false, r.status, null, `response body too large: ${rb.bytes} bytes over limit ${maxBodyBytes}`, 'toolarge')
+            }
+            text = rb.text
+        }
+        catch (err) {
+            if (get(err, 'name', '') === 'AbortError') {
+                return rs(false, r.status, null, `request timeout over ${timeoutMs}ms while reading body`, 'timeout')
+            }
+            return rs(false, r.status, null, `read body error: ${redactText(get(err, 'message', 'unknown'), redact)}`, 'network')
+        }
+
+    }
+    finally {
+        clearTimeout(idTimer)
+    }
+
+    //auth, 401代表憑證本身不被接受(過期或撤銷)。此處不給處置指引——各家正確處置不同
+    //(Claude/Codex之CLI會於執行時自行刷新, 存檔之refresh token仍有效, 貿然指引「重新登入」是多餘的), 由各轉接器補述
+    if (r.status === 401) {
+        return rs(false, r.status, null, `unauthorized(401), credential rejected (expired or revoked): ${snip(text)}`, 'auth')
+    }
+
+    //forbidden, 403代表憑證有效但此帳號無權存取該資源, 與401分流(401重新登入可解, 403重新登入一百次也一樣)
+    if (r.status === 403) {
+        return rs(false, r.status, null, `forbidden(403), credential valid but this account has no access to the resource (plan does not include it, or the service no longer serves this account tier): ${snip(text)}`, 'forbidden')
+    }
+
+    //ratelimit, 429為端點自身之查詢頻率限制, 與訂閱額度用罄無關
+    if (r.status === 429) {
+        return rs(false, r.status, null, `rate limited(429) by usage endpoint: ${snip(text)}`, 'ratelimit')
+    }
+
+    //http
+    if (!r.ok) {
+        return rs(false, r.status, null, `http error(${r.status}): ${snip(text)}`, 'http')
+    }
+
+    //data
+    let data = null
+    try {
+        data = JSON.parse(text)
+    }
+    catch (err) {
+        return rs(false, r.status, null, `invalid json: ${snip(text)}`, 'parse')
+    }
+
+    return rs(true, r.status, data, '', '')
+}
+
+
+export default fetchQuotaJson

package/src/quota/fromCodexUsageHttp.mjs

@@ -0,0 +1,263 @@
+import get from 'lodash-es/get.js'
+import isestr from 'wsemi/src/isestr.mjs'
+import isearr from 'wsemi/src/isearr.mjs'
+import iseobj from 'wsemi/src/iseobj.mjs'
+import isnum from 'wsemi/src/isnum.mjs'
+import cdbl from 'wsemi/src/cdbl.mjs'
+import toQuotaScopedLabel from './toQuotaScopedLabel.mjs'
+import toQuotaWindow from './toQuotaWindow.mjs'
+
+
+// fromCodexUsageHttp.mjs — 將chatgpt.com之/wham/usage回應對映為統一結構
+//
+// 【為何獨立成檔】此端點為ChatGPT前端自用之內部端點, 欄位形狀已知會變(尤其additional_rate_limits),
+//   對映邏輯獨立後可用離線fixture斷言, 不必每次都靠真帳號才能驗證。
+//
+// 【additional_rate_limits之寬容解析】本機帳號此欄實測為null, 形狀取自同類工具codex-reset-checker
+//   之測試fixture(其作者觀察到的真實回應): 集合可為陣列或以名稱為鍵之物件; 單筆之識別可為
+//   limit_name / metered_limit_name / name / id; 顯示名可為display_name / title; 窗口可在單筆頂層、
+//   rate_limit之下(snake或camel), 或單筆本身就是一個窗口(直接帶used_percent, 或置於window鍵);
+//   直接窗口不分primary/secondary時, 以名稱含weekly/secondary/reserve或窗口長度≥6天判為週限額。
+//   已知名稱: codex-spark(GPT-5.3-Codex-Spark)、gpt-reserve(Luna reserve之週限額)。
+//   任何欄位缺漏皆「該窗口不列入」而不拋錯, 原始回應由呼叫端保留於raw。
+
+
+//直接窗口判為週限額之窗口長度門檻(秒)
+let SEC_WEEKLY_MIN = 6 * 86400
+
+
+/**
+ * 取第一個為非空字串之鍵值
+ *
+ * @param {Object} o 輸入物件
+ * @param {Array} keys 輸入鍵陣列
+ * @returns {String} 回傳字串, 皆無回傳''
+ */
+function firstStr(o, keys) {
+    for (let k of keys) {
+        let v = get(o, k, '')
+        if (isestr(v)) {
+            return v
+        }
+    }
+    return ''
+}
+
+
+/**
+ * 將單一窗口{used_percent, limit_window_seconds, reset_at, reset_after_seconds}正規化
+ *
+ * @param {Object} o 輸入窗口物件
+ * @param {String} key 輸入窗口鍵字串
+ * @param {String} scope 輸入範圍字串
+ * @returns {Object|null} 回傳統一窗口物件, 輸入非物件回傳null
+ */
+function fromWindow(o, key, scope) {
+    if (!iseobj(o)) {
+        return null
+    }
+    let ws = get(o, 'limit_window_seconds', null)
+    let windowSeconds = isnum(ws) ? cdbl(ws) : null
+    return toQuotaWindow({
+        key,
+        label: toQuotaScopedLabel(windowSeconds, scope),
+        windowSeconds,
+        usedPercent: get(o, 'used_percent', null),
+        resetAt: get(o, 'reset_at', ''),
+        resetAfterSeconds: get(o, 'reset_after_seconds', null),
+        scope,
+    })
+}
+
+
+/**
+ * 取出additional_rate_limits之集合並統一為陣列
+ *
+ * @param {Object} data 輸入回應物件
+ * @returns {Array} 回傳單筆物件陣列, 無則[]
+ */
+function collectAdditional(data) {
+    let cands = [
+        get(data, 'additional_rate_limits', null),
+        get(data, 'rate_limit.additional_rate_limits', null),
+    ]
+    for (let c of cands) {
+        if (isearr(c)) {
+            return c
+        }
+        if (iseobj(c)) {
+            return Object.keys(c).map((k) => {
+                let v = c[k]
+                if (!iseobj(v)) {
+                    return v
+                }
+                let nm = firstStr(v, ['limit_name', 'name', 'id'])
+                return { ...v, limit_name: nm === '' ? k : nm }
+            })
+        }
+    }
+    return []
+}
+
+
+/**
+ * 自單筆取出指定窗口(頂層、rate_limit、rateLimit之下, snake或camel)
+ *
+ * @param {Object} it 輸入單筆物件
+ * @param {String} snake 輸入snake鍵, 例如'primary_window'
+ * @param {String} camel 輸入camel鍵, 例如'primaryWindow'
+ * @returns {Object|null} 回傳窗口物件, 無回傳null
+ */
+function pickWindow(it, snake, camel) {
+    for (let c of [it, get(it, 'rate_limit', null), get(it, 'rateLimit', null)]) {
+        if (!iseobj(c)) {
+            continue
+        }
+        let w = get(c, snake, null)
+        if (!iseobj(w)) {
+            w = get(c, camel, null)
+        }
+        if (iseobj(w)) {
+            return w
+        }
+    }
+    return null
+}
+
+
+/**
+ * 單筆本身即為窗口時取出之
+ *
+ * @param {Object} it 輸入單筆物件
+ * @returns {Object|null} 回傳窗口物件, 無回傳null
+ */
+function directWindow(it) {
+    if (!iseobj(it)) {
+        return null
+    }
+    if (get(it, 'used_percent', undefined) !== undefined) {
+        return it
+    }
+    let w = get(it, 'window', null)
+    if (iseobj(w)) {
+        return w
+    }
+    let rl = get(it, 'rate_limit', null)
+    if (iseobj(rl) && get(rl, 'used_percent', undefined) !== undefined) {
+        return rl
+    }
+    return null
+}
+
+
+/**
+ * 將chatgpt.com之/wham/usage回應對映為統一結構
+ *
+ * 主窗口(rate_limit.primary_window / secondary_window)、程式碼審查限額(code_review_rate_limit)、
+ * 以及寬容解析之additional_rate_limits皆納入windows；額外限額之窗口鍵為「<識別>:primary|secondary」，
+ * scope為其顯示名或識別。任何欄位缺漏皆略過該窗口而不拋錯
+ *
+ * @param {Object} data 輸入/wham/usage之回應物件
+ * @returns {Object} 回傳物件，內含email(字串，無則'')、plan(字串，無則'')、windows(統一窗口陣列)、credits(點數與重置券資訊物件)
+ * @example
+ *
+ * import fromCodexUsageHttp from './src/quota/fromCodexUsageHttp.mjs'
+ *
+ * let m = fromCodexUsageHttp({
+ *     email: 'a@b.c',
+ *     plan_type: 'plus',
+ *     rate_limit: { primary_window: { used_percent: 42, limit_window_seconds: 18000, reset_after_seconds: 100 } },
+ *     additional_rate_limits: [{ limit_name: 'codex-spark', primary_window: { used_percent: 12, limit_window_seconds: 18000 } }],
+ * })
+ * console.log(m.windows.map((w) => `${w.key}=${w.label}`))
+ * // => [ 'primary=5小時', 'codex-spark:primary=5小時(codex-spark)' ]
+ *
+ */
+function fromCodexUsageHttp(data) {
+
+    //email與plan
+    let email = firstStr(data, ['email'])
+    let plan = firstStr(data, ['plan_type'])
+
+    //windows, 主窗口
+    let windows = []
+    for (let k of ['primary', 'secondary']) {
+        let w = fromWindow(get(data, `rate_limit.${k}_window`, null), k, '')
+        if (w !== null) {
+            windows.push(w)
+        }
+    }
+
+    //code review限額, 與對話額度分開計算
+    for (let k of ['primary', 'secondary']) {
+        let w = fromWindow(get(data, `code_review_rate_limit.${k}_window`, null), `code_review:${k}`, 'code review')
+        if (w !== null) {
+            windows.push(w)
+        }
+    }
+
+    //additional_rate_limits, 寬容解析
+    let addi = collectAdditional(data)
+    for (let i = 0; i < addi.length; i++) {
+        let it = addi[i]
+        if (!iseobj(it)) {
+            continue
+        }
+
+        //id與scope
+        let id = firstStr(it, ['limit_name', 'metered_limit_name', 'name', 'id'])
+        if (id === '') {
+            id = `additional_${i + 1}`
+        }
+        let display = firstStr(it, ['display_name', 'title', 'name', 'limit_name', 'metered_limit_name'])
+        let scope = display === '' ? id : display
+        let identity = `${id} ${display}`.toLowerCase()
+
+        //窗口, 先找明確之primary/secondary, 皆無時把單筆本身當窗口並以名稱或長度判別週限額
+        let pri = pickWindow(it, 'primary_window', 'primaryWindow')
+        let sec = pickWindow(it, 'secondary_window', 'secondaryWindow')
+        if (pri === null && sec === null) {
+            let d = directWindow(it)
+            if (d !== null) {
+                let ws = get(d, 'limit_window_seconds', null)
+                let weekly = /weekly|secondary|reserve/.test(identity) || (isnum(ws) && cdbl(ws) >= SEC_WEEKLY_MIN)
+                if (weekly) {
+                    sec = d
+                }
+                else {
+                    pri = d
+                }
+            }
+        }
+
+        let wp = fromWindow(pri, `${id}:primary`, scope)
+        if (wp !== null) {
+            windows.push(wp)
+        }
+        let ws2 = fromWindow(sec, `${id}:secondary`, scope)
+        if (ws2 !== null) {
+            windows.push(ws2)
+        }
+    }
+
+    //credits, 點數餘額與「額度重置券」(可提前重置窗口)與限額狀態
+    let credits = {
+        hasCredits: get(data, 'credits.has_credits', false),
+        unlimited: get(data, 'credits.unlimited', false),
+        balance: get(data, 'credits.balance', ''),
+        resetCreditsAvailable: get(data, 'rate_limit_reset_credits.available_count', null),
+        spendControlReached: get(data, 'spend_control.reached', false),
+        rateLimitReachedType: get(data, 'rate_limit_reached_type', null),
+        individualLimit: get(data, 'spend_control.individual_limit', null),
+    }
+
+    return {
+        email,
+        plan,
+        windows,
+        credits,
+    }
+}
+
+
+export default fromCodexUsageHttp