w-dispatch-ai 1.0.21 → 1.0.23

package/src/quota/getQuotaCodex.mjs

@@ -0,0 +1,443 @@
+import os from 'os'
+import path from 'path'
+import get from 'lodash-es/get.js'
+import isobj from 'wsemi/src/isobj.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import iseobj from 'wsemi/src/iseobj.mjs'
+import isnum from 'wsemi/src/isnum.mjs'
+import cdbl from 'wsemi/src/cdbl.mjs'
+import execCliJsonRpc from 'wsemi/src/execCliJsonRpc.mjs'
+import castPintOr from '../castPintOr.mjs'
+import dfQuotaTimeoutMs from './dfQuotaTimeoutMs.mjs'
+import readJsonOrNull from './readJsonOrNull.mjs'
+import fetchQuotaJson from './fetchQuotaJson.mjs'
+import fromCodexUsageHttp from './fromCodexUsageHttp.mjs'
+import toQuotaScopedLabel from './toQuotaScopedLabel.mjs'
+import toQuotaWindow from './toQuotaWindow.mjs'
+import toQuotaResult from './toQuotaResult.mjs'
+
+
+// getQuotaCodex.mjs — 查詢Codex(ChatGPT訂閱)帳號之當前額度
+//
+// 【主路徑: codex app-server(第一方協定), 2026-09-05本機實測】
+//   `codex app-server --stdio` JSON-RPC: account/read → {account:{type:'chatgpt',email,planType}}(0.4s);
+//   account/rateLimits/read → {rateLimits:{primary,secondary,credits,planType,...}, rateLimitsByLimitId, rateLimitResetCredits}(1.4s)。
+//   認證與權杖刷新由codex自理, 本路徑不讀auth.json、不碰任何token; app-server子進程繼承本進程環境,
+//   故查的是本進程CODEX_HOME(未設則~/.codex)所指之帳號——opt.codexHome不影響此路徑, 只用於下方備援;
+//   要讓主路徑查別的目錄, 須於本進程環境設CODEX_HOME, 或以useAppServer:false改走備援。
+//   Codex Desktop/IDE走同一協定, 有`codex app-server generate-json-schema`可產schema, 遠比
+//   chatgpt.com之內部端點穩。同類工具wakamex/codex-cli-usage亦以此為主路徑。
+//   工作階段由wsemi之execCliJsonRpc(1.8.85起)承擔: Windows之.cmd解析、維持stdin開啟直到回應到齊、
+//   stdin.end()令其自行退出、逾寬限樹殺、以及「收尾之退出不算失敗」皆在其內; 本檔只負責
+//   握手內容(initialize之clientInfo、initialized通知)與codex專屬之回應對映。
+//   rateLimitResetCredits(額度重置券)由此路徑取得, 實測含id/title/description/grantedAt/expiresAt,
+//   比chatgpt.com之rate-limit-reset-credits專用端點更完整; 兌換重置券亦有第一方方法
+//   account/rateLimitResetCredit/consume({idempotencyKey, creditId?}), 屬動作非查詢, 本檔刻意不做。
+//
+// 【備援: GET https://chatgpt.com/backend-api/wham/usage】codex不存在、版本無app-server、
+//   或RPC失敗時退回直打(實測200), 憑證取自<opt.codexHome|CODEX_HOME|~/.codex>/auth.json(opt.codexHome僅於此生效); 該回應本身即帶
+//   email與plan_type。此為ChatGPT前端自用之內部端點, 路徑與欄位可能隨時變動, 對映邏輯獨立於
+//   fromCodexUsageHttp以便用離線fixture驗證; 錯誤訊息一律先遮蔽權杖與帳號ID。
+//
+// 【認證模式】auth.json之auth_mode欄位實測存在(本機'chatgpt'); API key模式下無tokens而有
+//   OPENAI_API_KEY, 此模式按用量計費、無訂閱額度窗口, 回unsupported而非誤導其去登入。
+//   app-server之account.type同義(非'chatgpt'即非訂閱)。
+//
+// 【為何備援不自行刷新權杖】auth.json之access_token實測壽命10天且由codex於執行時自行刷新;
+//   監控程式不擁有憑證生命週期(理由同getQuotaClaude), 401時指引執行一次codex即可。
+
+
+//備援端點與其UA/originator(Codex CLI對此端點之自我標識)
+let URL_USAGE = 'https://chatgpt.com/backend-api/wham/usage'
+let DEFAULT_UA = 'codex-cli/0.153.0'
+let DEFAULT_ORIGINATOR = 'codex_cli_rs'
+
+
+//app-server之請求序列: 握手(initialize須帶clientInfo; initialized為通知)後讀帳號與額度
+let DEFAULT_EXE = 'codex'
+let RPC_REQUESTS = [
+    { method: 'initialize', params: { clientInfo: { name: 'w-dispatch-ai', title: 'w-dispatch-ai', version: '1.0.0' } } },
+    { notify: 'initialized', params: {} },
+    { method: 'account/read', params: {} },
+    { method: 'account/rateLimits/read', params: {} },
+]
+
+
+/**
+ * 解出JWT之payload, 僅供顯示用途, 不驗簽
+ *
+ * @param {String} jwt 輸入JWT字串
+ * @returns {Object|null} 回傳payload物件, 解析失敗回傳null
+ */
+function decodeJwtPayload(jwt) {
+    try {
+        let ss = jwt.split('.')
+        if (ss.length < 2) {
+            return null
+        }
+        return JSON.parse(Buffer.from(ss[1], 'base64url').toString('utf8'))
+    }
+    catch (err) {
+        return null
+    }
+}
+
+
+/**
+ * 將app-server之單一窗口(primary/secondary)正規化為統一窗口物件
+ *
+ * @param {Object} o 輸入窗口物件{usedPercent, windowDurationMins, resetsAt}
+ * @param {String} key 輸入窗口鍵字串
+ * @param {String} scope 輸入範圍字串
+ * @returns {Object|null} 回傳統一窗口物件, 輸入非物件回傳null
+ */
+function fromRpcWindow(o, key, scope) {
+    if (!iseobj(o)) {
+        return null
+    }
+    let mins = get(o, 'windowDurationMins', null)
+    let windowSeconds = isnum(mins) ? cdbl(mins) * 60 : null
+    return toQuotaWindow({
+        key,
+        label: toQuotaScopedLabel(windowSeconds, scope),
+        windowSeconds,
+        usedPercent: get(o, 'usedPercent', null),
+        resetAt: get(o, 'resetsAt', ''),
+        scope,
+    })
+}
+
+
+/**
+ * 以app-server取得額度並正規化
+ *
+ * @param {Object} opt 輸入設定物件
+ * @returns {Promise} 回傳結果片段物件{ok, email, plan, accountType, windows, credits, raw, error, errorType}
+ */
+async function viaAppServer(opt) {
+
+    //exe
+    let exe = get(opt, 'exe', null)
+    if (!isestr(exe)) {
+        exe = DEFAULT_EXE
+    }
+
+    //rpc, errorType為params/notfound/timeout/exit/rpc
+    let r = await execCliJsonRpc(exe, ['app-server', '--stdio'], RPC_REQUESTS, {
+        timeoutMs: get(opt, 'timeoutMs', null),
+    })
+    if (!r.ok) {
+        return { ok: false, error: r.error, errorType: r.errorType, raw: { appServer: { error: r.error, errorType: r.errorType, exitCode: r.exitCode, responses: r.responses } } }
+    }
+
+    let acc = get(r.results, ['account/read', 'account'], null)
+    let rl = get(r.results, ['account/rateLimits/read'], null)
+
+    //account, null代表codex尚未登入
+    if (!iseobj(acc)) {
+        return { ok: false, notLoggedIn: true, error: 'codex app-server reports not logged in (account is null); run [codex login] first', errorType: 'notfound', raw: { appServer: r.results } }
+    }
+    let email = get(acc, 'email', '')
+    let plan = get(acc, 'planType', '')
+    let accountType = get(acc, 'type', '')
+
+    //accountType, 非chatgpt(例如apikey)即非訂閱, 無額度窗口
+    if (isestr(accountType) && accountType !== 'chatgpt') {
+        return {
+            ok: false,
+            email,
+            plan,
+            accountType,
+            error: `codex is logged in with [${accountType}] mode; this mode is billed by usage and has no 5-hour/7-day subscription quota windows`,
+            errorType: 'unsupported',
+            raw: { appServer: r.results },
+        }
+    }
+
+    //windows, 彙總窗口為主; rateLimitsByLimitId內與彙總同id者略過, 其餘以limitId為範圍逐一納入
+    let windows = []
+    let agg = get(rl, 'rateLimits', null)
+    let aggId = get(agg, 'limitId', 'codex')
+    let wPri = fromRpcWindow(get(agg, 'primary', null), 'primary', '')
+    if (wPri !== null) {
+        windows.push(wPri)
+    }
+    let wSec = fromRpcWindow(get(agg, 'secondary', null), 'secondary', '')
+    if (wSec !== null) {
+        windows.push(wSec)
+    }
+    let byId = get(rl, 'rateLimitsByLimitId', null)
+    if (iseobj(byId)) {
+        for (let limitId of Object.keys(byId)) {
+            if (limitId === aggId) {
+                continue
+            }
+            let it = byId[limitId]
+            let scope = get(it, 'limitName', '')
+            if (!isestr(scope)) {
+                scope = limitId
+            }
+            for (let k of ['primary', 'secondary']) {
+                let w = fromRpcWindow(get(it, k, null), `${limitId}:${k}`, scope)
+                if (w !== null) {
+                    windows.push(w)
+                }
+            }
+        }
+    }
+
+    //credits, 點數餘額、額度重置券(Codex特有, 可提前重置窗口)與限額狀態
+    let credits = {
+        hasCredits: get(agg, 'credits.hasCredits', false),
+        unlimited: get(agg, 'credits.unlimited', false),
+        balance: get(agg, 'credits.balance', ''),
+        resetCreditsAvailable: get(rl, 'rateLimitResetCredits.availableCount', null),
+        resetCredits: get(rl, 'rateLimitResetCredits.credits', null),
+        spendControlReached: get(agg, 'spendControlReached', false),
+        rateLimitReachedType: get(agg, 'rateLimitReachedType', null),
+        individualLimit: get(agg, 'individualLimit', null),
+    }
+
+    //plan, account/read為先, 其次rateLimits
+    if (!isestr(plan)) {
+        plan = get(agg, 'planType', '')
+    }
+
+    return {
+        ok: true,
+        email,
+        plan,
+        accountType,
+        windows,
+        credits,
+        raw: { appServer: r.results },
+    }
+}
+
+
+/**
+ * 以備援端點取得額度並正規化
+ *
+ * @param {Object} opt 輸入設定物件
+ * @param {String} codexHome 輸入codex設定目錄字串
+ * @param {Number} timeoutMs 輸入逾時毫秒
+ * @returns {Promise} 回傳結果片段物件{ok, email, plan, windows, credits, raw, error, errorType}
+ */
+async function viaHttp(opt, codexHome, timeoutMs) {
+
+    //env, 同主函數之注入來源
+    let env = get(opt, 'env', null)
+    if (!isobj(env)) {
+        env = process.env
+    }
+
+    //auth
+    let fpAuth = path.join(codexHome, 'auth.json')
+    let auth = readJsonOrNull(fpAuth)
+    let token = get(auth, 'tokens.access_token', '')
+    let accountId = get(auth, 'tokens.account_id', '')
+
+    //email與plan, 先由id_token取得(查詢失敗時仍能指出本機綁定之帳號), 查詢成功後以回應為準
+    let email = ''
+    let plan = ''
+    let idToken = get(auth, 'tokens.id_token', '')
+    if (isestr(idToken)) {
+        let pl = decodeJwtPayload(idToken)
+        let e = get(pl, 'email', '')
+        if (isestr(e)) {
+            email = e
+        }
+        //claim名本身含點號, 路徑須給陣列形式, 給字串會被lodash切開而永遠取不到
+        let p = get(pl, ['https://api.openai.com/auth', 'chatgpt_plan_type'], '')
+        if (isestr(p)) {
+            plan = p
+        }
+    }
+
+    //check token
+    if (!isestr(token)) {
+
+        //unsupported, API key模式: auth.json只有OPENAI_API_KEY而無tokens
+        let apiKey = get(auth, 'OPENAI_API_KEY', '')
+        if (isestr(apiKey) || isestr(get(env, 'OPENAI_API_KEY', ''))) {
+            return { ok: false, email, plan, error: 'codex is running in API key mode (auth.json has OPENAI_API_KEY but no tokens); this mode is billed by usage and has no subscription quota windows', errorType: 'unsupported' }
+        }
+
+        return { ok: false, email, plan, error: `Codex CLI credential not found (${fpAuth}); run [codex login] first`, errorType: 'notfound' }
+    }
+
+    //headers
+    let userAgent = get(opt, 'userAgent', null)
+    if (!isestr(userAgent)) {
+        userAgent = DEFAULT_UA
+    }
+    let originator = get(opt, 'originator', null)
+    if (!isestr(originator)) {
+        originator = DEFAULT_ORIGINATOR
+    }
+    let headers = {
+        'Authorization': `Bearer ${token}`,
+        'User-Agent': userAgent,
+        originator,
+    }
+    if (isestr(accountId)) {
+        headers['ChatGPT-Account-ID'] = accountId
+    }
+
+    //fetch, 錯誤訊息中之權杖與帳號ID一律遮蔽
+    let usageUrl = get(opt, 'usageUrl', null)
+    if (!isestr(usageUrl)) {
+        usageUrl = URL_USAGE
+    }
+    let r = await fetchQuotaJson(usageUrl, { headers, timeoutMs, redact: [token, accountId] })
+    if (!r.ok) {
+        let msg = r.error
+        if (r.errorType === 'auth') {
+            msg = `${msg} → codex refreshes the token on every run; run any codex command then retry, and only fall back to [codex login] if it still fails`
+        }
+        return { ok: false, email, plan, error: msg, errorType: r.errorType }
+    }
+
+    //map, 回應之帳號與方案為權威值
+    let m = fromCodexUsageHttp(r.data)
+    if (isestr(m.email)) {
+        email = m.email
+    }
+    if (isestr(m.plan)) {
+        plan = m.plan
+    }
+
+    return { ok: true, email, plan, windows: m.windows, credits: m.credits, raw: { usage: r.data } }
+}
+
+
+/**
+ * 查詢Codex(ChatGPT訂閱)帳號之當前額度
+ *
+ * 主路徑以codex app-server之JSON-RPC取得帳號與額度(認證與刷新由codex自理)，
+ * codex不存在或RPC失敗時退回直打chatgpt.com之用量端點。
+ * 額度綁定本機Codex CLI之登入憑證，無「給email查任意帳號」之公開介面，
+ * 故email參數之作用為比對——不符時ok為false且matched為false，並於error載明本機實際登入之帳號；
+ * 未給email時不比對。本函數不會reject，一律以結果物件之ok與error欄位回報成敗
+ *
+ * @param {String} [email=''] 輸入欲查詢之帳號email字串，預設''代表不比對而直接回報本機當前帳號
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.exe='codex'] 輸入codex執行檔名稱或路徑字串，預設'codex'
+ * @param {Boolean} [opt.useAppServer=true] 輸入是否以app-server為主路徑布林值，false代表直接走備援端點，預設true
+ * @param {Boolean} [opt.fallbackHttp=true] 輸入app-server失敗時是否退回備援端點布林值，預設true
+ * @param {String} [opt.codexHome] 輸入codex設定目錄字串，僅備援路徑讀其auth.json時生效；app-server主路徑之子進程繼承本進程環境，查的是本進程CODEX_HOME所指之帳號，不受此參數影響（要讓主路徑查別的目錄，須於本進程環境設CODEX_HOME，或以useAppServer:false改走備援），預設取環境變數CODEX_HOME，未設則<homeDir>/.codex
+ * @param {String} [opt.homeDir=os.homedir()] 輸入家目錄字串，僅於未指定codexHome且未設環境變數時使用
+ * @param {String} [opt.userAgent='codex-cli/0.153.0'] 輸入備援端點之User-Agent字串
+ * @param {String} [opt.originator='codex_cli_rs'] 輸入備援端點之originator標頭字串
+ * @param {String} [opt.usageUrl='https://chatgpt.com/backend-api/wham/usage'] 輸入備援端點網址字串，供測試指向假伺服器或經企業代理，預設官方端點
+ * @param {Object} [opt.env=process.env] 輸入環境變數來源物件(讀CODEX_HOME與API key模式判定用之OPENAI_API_KEY)，供測試隔離本機環境，預設process.env
+ * @param {Number} [opt.timeoutMs=20000] 輸入逾時毫秒正整數(app-server整體或單次HTTP)，預設20000
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok、provider('codex')、email、matched、plan(例如'plus')、planTier(空字串)、source('codex-app-server'或'chatgpt-wham-usage-api')、windows(含5小時與7天，另有依limitId分列之窗口)、credits(點數、重置券清單、限額狀態)、raw、error、errorType、durationMs，本函數不會reject
+ * @example
+ * //need codex cli logged in
+ *
+ * import getQuotaCodex from './src/quota/getQuotaCodex.mjs'
+ *
+ * let test = async () => {
+ *     let r = await getQuotaCodex('firsemisphere@gmail.com')
+ *     console.log(r.ok, r.plan, r.source)
+ *     // => true plus codex-app-server
+ *     console.log(r.windows[0].label, r.windows[0].usedPercent)
+ *     // => 5小時 37 (百分比為查詢當下之即時值, 每次不同)
+ * }
+ * test()
+ *
+ */
+async function getQuotaCodex(email = '', opt = {}) {
+
+    let t0 = Date.now()
+
+    //emailWant
+    let emailWant = isestr(email) ? email : ''
+
+    //env, 環境變數來源可注入(測試以替身隔離本機環境), 預設process.env
+    let env = get(opt, 'env', null)
+    if (!isobj(env)) {
+        env = process.env
+    }
+
+    //homeDir
+    let homeDir = get(opt, 'homeDir', null)
+    if (!isestr(homeDir)) {
+        homeDir = os.homedir()
+    }
+
+    //codexHome, 依序取opt、CODEX_HOME、<homeDir>/.codex(codex --help: auth still uses CODEX_HOME);
+    //僅備援路徑用, app-server主路徑之子進程繼承本進程環境而不看此值(見檔頭)
+    let codexHome = get(opt, 'codexHome', null)
+    if (!isestr(codexHome)) {
+        codexHome = get(env, 'CODEX_HOME', '')
+        if (!isestr(codexHome)) {
+            codexHome = path.join(homeDir, '.codex')
+        }
+    }
+
+    //timeoutMs
+    let timeoutMs = castPintOr(get(opt, 'timeoutMs', null), dfQuotaTimeoutMs)
+
+    //useAppServer與fallbackHttp
+    let useAppServer = get(opt, 'useAppServer', true) !== false
+    let fallbackHttp = get(opt, 'fallbackHttp', true) !== false
+
+    //fin
+    let fin = (source, o) => {
+        return toQuotaResult('codex', {
+            emailWant,
+            source,
+            durationMs: Date.now() - t0,
+            ...o,
+        })
+    }
+
+    //app-server
+    let appErr = null
+    if (useAppServer) {
+        let a = await viaAppServer({ ...opt, timeoutMs })
+        if (a.ok) {
+            return fin('codex-app-server', {
+                email: a.email,
+                plan: a.plan,
+                windows: a.windows,
+                credits: a.credits,
+                raw: { accountType: a.accountType, ...a.raw },
+            })
+        }
+
+        //unsupported與「尚未登入」(notLoggedIn旗標, 不靠錯誤字串比對)為帳號狀態, 備援亦無解, 直接回報
+        if (a.errorType === 'unsupported' || a.notLoggedIn === true) {
+            return fin('codex-app-server', { email: a.email, plan: a.plan, error: a.error, errorType: a.errorType, raw: a.raw })
+        }
+        appErr = a
+        if (!fallbackHttp) {
+            return fin('codex-app-server', { error: a.error, errorType: a.errorType, raw: a.raw })
+        }
+    }
+
+    //http fallback
+    let h = await viaHttp(opt, codexHome, timeoutMs)
+    let note = appErr !== null ? ` (app-server path failed: ${appErr.error})` : ''
+    if (!h.ok) {
+        return fin('chatgpt-wham-usage-api', {
+            email: h.email,
+            plan: h.plan,
+            error: `${h.error}${note}`,
+            errorType: h.errorType,
+            raw: appErr !== null ? appErr.raw : null,
+        })
+    }
+    return fin('chatgpt-wham-usage-api', {
+        email: h.email,
+        plan: h.plan,
+        windows: h.windows,
+        credits: h.credits,
+        raw: { codexHome, appServerError: appErr !== null ? appErr.error : '', ...h.raw },
+    })
+}
+
+
+export default getQuotaCodex

package/src/quota/readJsonOrNull.mjs

@@ -0,0 +1,41 @@
+import get from 'lodash-es/get.js'
+import fsReadJson from 'wsemi/src/fsReadJson.mjs'
+
+
+// readJsonOrNull.mjs — 讀取JSON檔, 任何失敗一律回null
+//
+// 【為何獨立成檔】三個額度轉接器都要讀各自CLI之憑證或設定檔, 且處置一致(檔案不存在、
+//   無權限、內容非JSON皆視為「取不到」而非錯誤); 同一段判斷曾各自手寫三份,
+//   依全域規範「同一規則手寫≥2處即補丁訊號」收斂於此。
+//
+// 【為何包wsemi之fsReadJson而非自寫try/catch】fsReadJson已是套件內讀JSON之canonical實作
+//   (純JSON.parse, 無型別轉換), 以{ success }/{ error }回報; 本檔只把它收斂成
+//   「成功回值、失敗回null」之單一契約, 令呼叫端不必每處都判斷error鍵。
+
+
+/**
+ * 讀取JSON檔，任何失敗一律回傳null
+ *
+ * 檔案不存在、無讀取權限、內容非合法JSON三種情形對呼叫端而言皆為「取不到」，
+ * 無須區分，故一律回null，由呼叫端決定後續處置(例如回報未登入)
+ *
+ * @param {String} fp 輸入檔案路徑字串
+ * @returns {Object|Array|null} 回傳解析後之JSON值，讀取或解析失敗回傳null
+ * @example
+ *
+ * import readJsonOrNull from './src/quota/readJsonOrNull.mjs'
+ *
+ * console.log(readJsonOrNull('./package.json') !== null)
+ * // => true
+ *
+ * console.log(readJsonOrNull('./no-such-file.json'))
+ * // => null
+ *
+ */
+function readJsonOrNull(fp) {
+    let rj = fsReadJson(fp)
+    return get(rj, 'success', null)
+}
+
+
+export default readJsonOrNull

package/src/quota/toQuotaLabel.mjs

@@ -0,0 +1,74 @@
+import isnum from 'wsemi/src/isnum.mjs'
+import cdbl from 'wsemi/src/cdbl.mjs'
+
+
+// toQuotaLabel.mjs — 由額度窗口長度秒數推導人類可讀之中文標籤(單一來源)
+//
+// 【為何獨立成檔】toQuotaWindow推導預設標籤用它; 各轉接器對「帶模型別或群組別」之窗口
+//   須自組「7天(Fable)」「5小時(Gemini)」這類標籤, 也用它取基底。
+//   原版把此邏輯藏在toQuotaWindow內部, 轉接器只好各自手寫「7天(」字串,
+//   結果session窗口與weekly窗口之標籤不對稱(前者漏了「5小時」基底); 抽出後只剩一份規則。
+//
+// 【為何由秒數推導而非寫死】寫死「5小時/7天」等於把當下的窗口長度當成永久事實,
+//   供應商調整窗口時字面會說謊且無人察覺; 由秒數推導則窗口一變標籤即隨之正確。
+
+
+//每分鐘/每小時/每日之秒數
+let SEC_MIN = 60
+let SEC_HOUR = 3600
+let SEC_DAY = 86400
+
+
+/**
+ * 由額度窗口長度秒數推導人類可讀之中文標籤
+ *
+ * 能整除日數即以「N天」表示，其次「N小時」、「N分鐘」，皆不整除則「N秒」；
+ * 無效或非正數回傳空字串，令呼叫端可用空字串判斷「供應商未提供窗口長度」
+ *
+ * @param {Number} sec 輸入窗口長度秒數
+ * @returns {String} 回傳中文標籤字串，無效秒數回傳空字串
+ * @example
+ *
+ * import toQuotaLabel from './src/quota/toQuotaLabel.mjs'
+ *
+ * console.log(toQuotaLabel(18000))
+ * // => 5小時
+ *
+ * console.log(toQuotaLabel(604800))
+ * // => 7天
+ *
+ * console.log(toQuotaLabel(900))
+ * // => 15分鐘
+ *
+ * console.log(toQuotaLabel(null))
+ * // => (空字串)
+ *
+ */
+function toQuotaLabel(sec) {
+
+    //check, 無效或非正數無從推導
+    if (!isnum(sec) || cdbl(sec) <= 0) {
+        return ''
+    }
+    sec = cdbl(sec)
+
+    //day
+    if (sec % SEC_DAY === 0) {
+        return `${sec / SEC_DAY}天`
+    }
+
+    //hour
+    if (sec % SEC_HOUR === 0) {
+        return `${sec / SEC_HOUR}小時`
+    }
+
+    //minute
+    if (sec % SEC_MIN === 0) {
+        return `${sec / SEC_MIN}分鐘`
+    }
+
+    return `${sec}秒`
+}
+
+
+export default toQuotaLabel