w-dwdata-hub 1.0.0

package/src/fetchTpex3insti.mjs

@@ -0,0 +1,206 @@
+import get from 'lodash-es/get.js'
+import isestr from 'wsemi/src/isestr.mjs'
+import isearr from 'wsemi/src/isearr.mjs'
+import fetchWithRetry from './fetchWithRetry.mjs'
+import getOptFetch from './getOptFetch.mjs'
+import isYmd from './isYmd.mjs'
+import toRocDate from './toRocDate.mjs'
+
+
+//櫃買中心網站根網址
+let BASE_URL = 'https://www.tpex.org.tw'
+
+
+//本函數之預設抓取設定
+let DFLT = {
+    timeout: 15000,
+    maxRetries: 10,
+    baseDelayMs: 5000,
+    maxDelayMs: 30000,
+    label: 'fetch-tpex-3insti',
+}
+
+
+//TPEX 3insti_hedge端點之fields為「裸欄名」——買進股數/賣出股數/買賣超股數各重複7次
+//(外資不含自營 / 外資自營 / 外資合計 / 投信 / 自營自行 / 自營避險 / 自營合計), 群組標籤不在JSON內
+//故唯一可靠解法是以「固定位置」對應語意欄名(不可用欄名當key, 否則同名後者覆蓋前者、7組塌成1組)
+//明細欄名對齊TWSE T86(外陸資.../投信.../自營商...), 令下游TWSE與TPEX共用同一套key
+//末欄保留「三大法人買賣超股數合計」(下游有寫死讀此名者, 勿改)
+let TPEX_FIELD_MAP = [
+    '代號',
+    '名稱',
+    '外陸資買進股數(不含外資自營商)',
+    '外陸資賣出股數(不含外資自營商)',
+    '外陸資買賣超股數(不含外資自營商)',
+    '外資自營商買進股數',
+    '外資自營商賣出股數',
+    '外資自營商買賣超股數',
+    '外資及陸資買進股數',
+    '外資及陸資賣出股數',
+    '外資及陸資買賣超股數',
+    '投信買進股數',
+    '投信賣出股數',
+    '投信買賣超股數',
+    '自營商買進股數(自行買賣)',
+    '自營商賣出股數(自行買賣)',
+    '自營商買賣超股數(自行買賣)',
+    '自營商買進股數(避險)',
+    '自營商賣出股數(避險)',
+    '自營商買賣超股數(避險)',
+    '自營商買進股數',
+    '自營商賣出股數',
+    '自營商買賣超股數',
+    '三大法人買賣超股數合計',
+]
+
+
+/**
+ * 驗證TPEX回傳fields是否仍為預期結構
+ *
+ * 結構防呆(fail-loud), 驗證仍為「24欄、買進/賣出/買賣超循環×7」;
+ * 不符即拋錯(屬非暫時性錯誤故不重試), 避免API改版後靜默把外資的數字貼到投信頭上
+ *
+ * @param {Array} fields 輸入API回傳之欄名字串陣列
+ */
+function assertTpexFieldShape(fields) {
+
+    if (fields.length !== TPEX_FIELD_MAP.length) {
+        throw new Error(`TPEX 3insti: 欄數異常，預期 ${TPEX_FIELD_MAP.length} 得 ${fields.length}（疑似 API 改版，請重新校準 TPEX_FIELD_MAP）`)
+    }
+    if (!String(fields[0]).includes('代號') || !String(fields[1]).includes('名稱')) {
+        throw new Error(`TPEX 3insti: 前兩欄非「代號/名稱」（得「${fields[0]}」「${fields[1]}」，疑似 API 改版）`)
+    }
+    if (!String(fields[fields.length - 1]).includes('合計')) {
+        throw new Error(`TPEX 3insti: 末欄非「合計」（得「${fields[fields.length - 1]}」，疑似 API 改版）`)
+    }
+
+    let cycle = ['買進股數', '賣出股數', '買賣超股數']
+    for (let i = 2; i < fields.length - 1; i++) {
+        let expect = cycle[(i - 2) % 3]
+        if (String(fields[i]) !== expect) {
+            throw new Error(`TPEX 3insti: 第 ${i} 欄預期「${expect}」得「${fields[i]}」（疑似 API 改版，欄序已變）`)
+        }
+    }
+
+}
+
+
+/**
+ * 抓取櫃買中心(TPEX)上櫃三大法人買賣超
+ *
+ * 抓取指定日之上櫃三大法人買賣超(含自營商避險), 因API之fields為裸欄名且重複, 故以固定位置對應語意欄名;
+ * 套位置對應前先驗證欄位結構, 不符即拋錯以避免產生錯置之財務資料
+ *
+ * @param {String} dateStr 輸入日期YYYYMMDD字串
+ * @param {Array} [stockCodes] 輸入股票代號字串陣列，省略或空陣列表示全市場
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.baseUrl='https://www.tpex.org.tw'] 輸入櫃買中心根網址字串，供測試或改指向鏡像時覆寫
+ * @param {Integer} [opt.timeout=15000] 輸入單次請求逾時毫秒整數，預設15000
+ * @param {Integer} [opt.maxRetries=10] 輸入最大重試次數整數，含初始共執行maxRetries+1次，預設10
+ * @param {Integer} [opt.baseDelayMs=5000] 輸入重試之線性退避基礎毫秒整數，預設5000
+ * @param {Integer} [opt.maxDelayMs=30000] 輸入重試之線性退避上限毫秒整數，預設30000
+ * @param {Boolean} [opt.showLog=true] 輸入是否顯示過程訊息布林值，預設true
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件{source,date,data}，日期無效、無資料或欄位結構不符時reject回傳錯誤物件
+ * @example
+ *
+ * import fetchTpex3insti from './src/fetchTpex3insti.mjs'
+ *
+ * let test = async () => {
+ *
+ *     let r = await fetchTpex3insti('20260807', ['6488'])
+ *     console.log(r.source, r.data.length, r.data[0]['代號'])
+ *     // => 'tpex' 1 '6488'
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function fetchTpex3insti(dateStr, stockCodes, opt = {}) {
+
+    //check
+    if (!isestr(dateStr) || !/^\d{8}$/.test(dateStr)) {
+        throw new Error(`dateStr must be YYYYMMDD, got: ${dateStr}`)
+    }
+    if (!isYmd(dateStr)) {
+        //合法性驗證, 例如20260230雖符合8碼但日期不存在
+        throw new Error(`dateStr 不是合法日期: ${dateStr}`)
+    }
+
+    //baseUrl
+    let baseUrl = get(opt, 'baseUrl')
+    if (!isestr(baseUrl)) {
+        baseUrl = BASE_URL
+    }
+    baseUrl = baseUrl.replace(/\/+$/, '')
+
+    //optFetch
+    let optFetch = getOptFetch(opt, DFLT)
+    let showLog = optFetch.showLog
+
+    //targetCodes
+    let targetCodes = isearr(stockCodes) ? stockCodes : []
+
+    //url
+    let rocDateStr = toRocDate(dateStr)
+    let url = `${baseUrl}/web/stock/3insti/daily_trade/3itrade_hedge_result.php?l=zh-tw&t=D&d=${rocDateStr}&o=json`
+
+    if (showLog) {
+        console.log(`Fetching from: ${url}`)
+        console.log(`Target: ${targetCodes.length === 0 ? 'All Market' : targetCodes.join(', ')}`)
+    }
+
+    //data
+    let data = await fetchWithRetry(url, optFetch)
+
+    //check
+    if (!isearr(get(data, 'tables'))) {
+        throw new Error('TPEX 3insti: tables not found in response. Possibly a holiday or no data.')
+    }
+
+    //table, 此端點回tables[0]=資料表、tables[1]=空{}
+    //取含「代號」「名稱」表頭之資料表, 退而取tables[0], 避免未來新增其他資料表時誤抓
+    let tables = data.tables
+    let table = tables.find((t) => {
+        return Array.isArray(t.fields) &&
+            t.fields.some((f) => String(f).includes('代號')) &&
+            t.fields.some((f) => String(f).includes('名稱'))
+    }) || tables[0]
+
+    //fields, rawData
+    let fields = get(table, 'fields')
+    let rawData = get(table, 'data')
+    if (!Array.isArray(fields) || !Array.isArray(rawData)) {
+        throw new Error('TPEX 3insti: data/fields not found in table.')
+    }
+
+    //套位置對應前先驗結構(fields為裸欄名, 必須靠固定位置才能還原7組明細)
+    assertTpexFieldShape(fields)
+
+    //processedData
+    let processedData = rawData
+        .map((row) => {
+            let obj = {}
+            TPEX_FIELD_MAP.forEach((key, index) => {
+                let value = row[index]
+                if (typeof value === 'string') {
+                    value = value.trim()
+                }
+                obj[key] = value
+            })
+            return obj
+        })
+        .filter((item) => targetCodes.length === 0 || targetCodes.includes(item['代號']))
+
+    if (showLog) {
+        console.log(`Fetched ${processedData.length} records.`)
+    }
+
+    return { source: 'tpex', date: dateStr, data: processedData }
+}
+
+
+export { TPEX_FIELD_MAP }
+export default fetchTpex3insti

package/src/fetchTpexMargin.mjs

@@ -0,0 +1,176 @@
+import get from 'lodash-es/get.js'
+import isestr from 'wsemi/src/isestr.mjs'
+import isearr from 'wsemi/src/isearr.mjs'
+import fetchWithRetry from './fetchWithRetry.mjs'
+import getOptFetch from './getOptFetch.mjs'
+import isYmd from './isYmd.mjs'
+import toRocDate from './toRocDate.mjs'
+import parseIntComma from './parseIntComma.mjs'
+
+
+//櫃買中心網站根網址
+let BASE_URL = 'https://www.tpex.org.tw'
+
+
+//本函數之預設抓取設定
+let DFLT = {
+    timeout: 15000,
+    maxRetries: 10,
+    baseDelayMs: 5000,
+    maxDelayMs: 30000,
+    label: 'fetch-tpex-margin',
+}
+
+
+/**
+ * 抓取櫃買中心(TPEX)上櫃融資融券
+ *
+ * 抓取指定日之上櫃個股融資融券餘額並轉為結構化資料, 可指定股票代號陣列過濾;
+ * 選表以欄位同時含「資餘額」與「券餘額」比對, 失敗則退而取第一張有資料表, 並鎖定index6與index14兩錨點欄位驗證佈局,
+ * 不符即fail-loud, 避免固定index解析在API改版後靜默產生錯誤資料
+ *
+ * @param {String} dateStr 輸入日期YYYYMMDD字串
+ * @param {Array} [stockCodes] 輸入股票代號字串陣列，省略或空陣列表示全市場
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.baseUrl='https://www.tpex.org.tw'] 輸入櫃買中心根網址字串，供測試或改指向鏡像時覆寫
+ * @param {Integer} [opt.timeout=15000] 輸入單次請求逾時毫秒整數，預設15000
+ * @param {Integer} [opt.maxRetries=10] 輸入最大重試次數整數，含初始共執行maxRetries+1次，預設10
+ * @param {Integer} [opt.baseDelayMs=5000] 輸入重試之線性退避基礎毫秒整數，預設5000
+ * @param {Integer} [opt.maxDelayMs=30000] 輸入重試之線性退避上限毫秒整數，預設30000
+ * @param {Boolean} [opt.showLog=true] 輸入是否顯示過程訊息布林值，預設true
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件{source,date,count,data}，日期無效、無資料、欄位佈局不符或指定個股查無資料時reject回傳錯誤物件
+ * @example
+ *
+ * import fetchTpexMargin from './src/fetchTpexMargin.mjs'
+ *
+ * let test = async () => {
+ *
+ *     let r = await fetchTpexMargin('20260807', ['6488'])
+ *     console.log(r.source, r.count, r.data[0].code)
+ *     // => 'tpex_margin' 1 '6488'
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function fetchTpexMargin(dateStr, stockCodes, opt = {}) {
+
+    //check
+    if (!isestr(dateStr) || !/^\d{8}$/.test(dateStr)) {
+        throw new Error(`日期參數無效：格式須為 YYYYMMDD (收到 "${dateStr}")`)
+    }
+    if (!isYmd(dateStr)) {
+        throw new Error(`日期參數無效：不合法的日期 (${dateStr})`)
+    }
+
+    //baseUrl
+    let baseUrl = get(opt, 'baseUrl')
+    if (!isestr(baseUrl)) {
+        baseUrl = BASE_URL
+    }
+    baseUrl = baseUrl.replace(/\/+$/, '')
+
+    //optFetch
+    let optFetch = getOptFetch(opt, DFLT)
+    let showLog = optFetch.showLog
+
+    //targetCodes
+    let targetCodes = isearr(stockCodes) ? stockCodes.filter(Boolean) : []
+
+    //url
+    let rocDate = toRocDate(dateStr)
+    let url = `${baseUrl}/web/stock/margin_trading/margin_balance/margin_bal_result.php?l=zh-tw&d=${rocDate}&o=json`
+
+    if (showLog) {
+        console.log(`Fetching TPEX margin data: ${dateStr} (${rocDate})`)
+        console.log(`Target: ${targetCodes.length > 0 ? targetCodes.join(', ') : 'All Market'}`)
+        console.log(`URL: ${url}`)
+    }
+
+    //data
+    let data = await fetchWithRetry(url, optFetch)
+
+    //marginTable, TPEX格式: { stat: 'ok', tables: [{ title, fields, data }] }
+    //fields: ["代號","名稱","前資餘額(張)","資買","資賣","現償","資餘額","資屬證金","資使用率(%)",
+    //         "資限額","前券餘額(張)","券賣","券買","券償","券餘額","券屬證金","券使用率(%)","券限額","資券相抵(張)","備註"]
+    let tables = Array.isArray(data.tables) ? data.tables : []
+    let marginTable = tables.find((t) => {
+        return get(t, 'data.length', 0) > 0 &&
+            Array.isArray(t.fields) &&
+            t.fields.some((f) => String(f).includes('資餘額')) &&
+            t.fields.some((f) => String(f).includes('券餘額'))
+    }) || tables.find((t) => get(t, 'data.length', 0) > 0)
+    if (!marginTable || !isearr(get(marginTable, 'data'))) {
+        throw new Error('TPEX margin API returned no data. Possibly a holiday or data not yet available.')
+    }
+
+    //shape guard, 主比對失敗時會fallback取第一張有資料表, 若該表結構不同則下方固定index(2~19)會靜默解析錯欄位
+    //此處鎖定解析所依賴之兩個錨點欄位(index 6=資餘額、index 14=券餘額), 不符即fail-loud
+    let fields = Array.isArray(marginTable.fields) ? marginTable.fields : []
+    if (!String(fields[6] || '').includes('資餘額') || !String(fields[14] || '').includes('券餘額')) {
+        throw new Error(`TPEX 融資融券資料欄位佈局與預期不符（index6 應含「資餘額」實為「${fields[6] ?? ''}」、index14 應含「券餘額」實為「${fields[14] ?? ''}」）；可能 API 格式變更，停止解析以免產生錯誤資料`)
+    }
+
+    //rows
+    let rows = marginTable.data
+    if (targetCodes.length > 0) {
+        rows = rows.filter((row) => targetCodes.includes(String(row[0] || '').trim()))
+        if (rows.length === 0) {
+            throw new Error(`指定個股 ${targetCodes.join(',')} 不在上櫃融資融券資料中（可能為上市股或代碼有誤）`)
+        }
+    }
+
+    //parsedData
+    //idx: 0=代號, 1=名稱, 2=前資餘額, 3=資買, 4=資賣, 5=現償, 6=資餘額,
+    //     7=資屬證金, 8=資使用率, 9=資限額, 10=前券餘額, 11=券賣, 12=券買,
+    //     13=券償, 14=券餘額, 15=券屬證金, 16=券使用率, 17=券限額, 18=資券相抵, 19=備註
+    let parsedData = rows.map((row) => {
+
+        let marginPrev = parseIntComma(row[2])
+        let marginBuy = parseIntComma(row[3])
+        let marginSell = parseIntComma(row[4])
+        let marginBalance = parseIntComma(row[6])
+        let shortPrev = parseIntComma(row[10])
+        let shortSell = parseIntComma(row[11])
+        let shortBuy = parseIntComma(row[12])
+        let shortBalance = parseIntComma(row[14])
+
+        return {
+            code: String(row[0] || '').trim(),
+            name: String(row[1] || '').trim(),
+            marginBuy,
+            marginSell,
+            marginCashRepay: parseIntComma(row[5]),
+            marginPrevBalance: marginPrev,
+            marginBalance,
+            marginChange: marginBalance - marginPrev,
+            marginLimit: parseIntComma(row[9]),
+            shortSell,
+            shortBuy,
+            shortCashRepay: parseIntComma(row[13]),
+            shortPrevBalance: shortPrev,
+            shortBalance,
+            shortChange: shortBalance - shortPrev,
+            shortLimit: parseIntComma(row[17]),
+            offset: parseIntComma(row[18]),
+            note: String(row[19] || '').trim(),
+        }
+    })
+
+    if (showLog) {
+        console.log(`Fetched ${parsedData.length} records.`)
+    }
+
+    return {
+        source: 'tpex_margin',
+        date: dateStr,
+        count: parsedData.length,
+        data: parsedData,
+    }
+}
+
+
+export default fetchTpexMargin

package/src/fetchTpexStock.mjs

@@ -0,0 +1,127 @@
+import get from 'lodash-es/get.js'
+import isestr from 'wsemi/src/isestr.mjs'
+import isearr from 'wsemi/src/isearr.mjs'
+import fetchWithRetry from './fetchWithRetry.mjs'
+import getOptFetch from './getOptFetch.mjs'
+import isYmd from './isYmd.mjs'
+import toRocDate from './toRocDate.mjs'
+
+
+//櫃買中心網站根網址
+let BASE_URL = 'https://www.tpex.org.tw'
+
+
+//本函數之預設抓取設定
+let DFLT = {
+    timeout: 15000,
+    maxRetries: 10,
+    baseDelayMs: 5000,
+    maxDelayMs: 30000,
+    label: 'fetch-tpex-stock',
+}
+
+
+//下游依固定欄序讀取(index 0代號、2收盤、4-6開高低、7成交股數), 故驗證欄數下限
+//門檻8遠低於實際約17欄, 不會誤擋正常資料
+let MIN_COLUMNS = 8
+
+
+/**
+ * 抓取櫃買中心(TPEX)上櫃股價
+ *
+ * 抓取指定日之上櫃股票行情, 可指定股票代號陣列過濾;
+ * 選表優先以標題含「行情」比對, 避免未來新增其他資料表時誤抓, 並驗證欄數以避免API改版後靜默讀錯欄
+ *
+ * @param {String} dateStr 輸入日期YYYYMMDD字串
+ * @param {Array} [stockCodes] 輸入股票代號字串陣列，例如['6499','6610']，省略或空陣列表示全市場
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.baseUrl='https://www.tpex.org.tw'] 輸入櫃買中心根網址字串，供測試或改指向鏡像時覆寫
+ * @param {Integer} [opt.timeout=15000] 輸入單次請求逾時毫秒整數，預設15000
+ * @param {Integer} [opt.maxRetries=10] 輸入最大重試次數整數，含初始共執行maxRetries+1次，預設10
+ * @param {Integer} [opt.baseDelayMs=5000] 輸入重試之線性退避基礎毫秒整數，預設5000
+ * @param {Integer} [opt.maxDelayMs=30000] 輸入重試之線性退避上限毫秒整數，預設30000
+ * @param {Boolean} [opt.showLog=true] 輸入是否顯示過程訊息布林值，預設true
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件{source,date,count,data}，日期無效、無資料或指定個股查無資料時reject回傳錯誤物件
+ * @example
+ *
+ * import fetchTpexStock from './src/fetchTpexStock.mjs'
+ *
+ * let test = async () => {
+ *
+ *     let r = await fetchTpexStock('20260807', ['6488'])
+ *     console.log(r.source, r.count)
+ *     // => 'tpex' 1
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function fetchTpexStock(dateStr, stockCodes, opt = {}) {
+
+    //check, 函數入口驗日期, 令程式化呼叫不繞過CLI之檢核
+    if (!isYmd(dateStr)) {
+        throw new Error(`dateStr 須為合法之 YYYYMMDD 字串，得到: ${dateStr}`)
+    }
+
+    //baseUrl
+    let baseUrl = get(opt, 'baseUrl')
+    if (!isestr(baseUrl)) {
+        baseUrl = BASE_URL
+    }
+    baseUrl = baseUrl.replace(/\/+$/, '')
+
+    //optFetch
+    let optFetch = getOptFetch(opt, DFLT)
+    let showLog = optFetch.showLog
+
+    //targetCodes
+    let targetCodes = isearr(stockCodes) ? stockCodes : []
+
+    //url
+    let rocDate = toRocDate(dateStr)
+    let url = `${baseUrl}/web/stock/aftertrading/daily_close_quotes/stk_quote_result.php?l=zh-tw&d=${rocDate}&s=0,asc,0&o=json`
+
+    if (showLog) {
+        console.log(`Fetching TPEX data: ${dateStr} (${rocDate})`)
+        console.log(`Target: ${targetCodes.length > 0 ? targetCodes.join(', ') : 'All Market'}`)
+        console.log(`URL: ${url}`)
+    }
+
+    //data
+    let data = await fetchWithRetry(url, optFetch)
+
+    //TPEX API格式(2026年後): { stat, tables: [{ title: '上櫃股票行情', data: [...] }] }
+    //優先以title「行情」字樣比對, 避免未來新增其他資料表時誤抓
+    let tables = Array.isArray(data.tables) ? data.tables : []
+    let targetTable = tables.find((t) => get(t, 'title', '').includes('行情') && get(t, 'data.length', 0) > 0) ||
+        tables.find((t) => get(t, 'data.length', 0) > 0)
+    let rows = get(targetTable, 'data')
+
+    //check
+    if (!isearr(rows)) {
+        throw new Error('TPEX API returned no data. Possibly a holiday or data not yet available.')
+    }
+
+    //shape sanity, 驗證選中表欄數符合預期, 避免API改版後靜默讀錯欄
+    if (!Array.isArray(rows[0]) || rows[0].length < MIN_COLUMNS) {
+        throw new Error(`TPEX 行情資料欄數不符預期（首列 ${Array.isArray(rows[0]) ? rows[0].length : 'N/A'} 欄，應 >= ${MIN_COLUMNS}），可能 API 格式變更`)
+    }
+
+    //resultData
+    let resultData = rows
+    if (targetCodes.length > 0) {
+        resultData = resultData.filter((row) => targetCodes.includes(row[0]))
+        if (resultData.length === 0) {
+            //整體有資料但過濾後為空 → 個股不在上櫃市場, 與整體無資料之錯誤訊息明確區分
+            throw new Error(`指定個股 ${targetCodes.join(',')} 在 ${dateStr} 之上櫃資料中查無資料（可能為上市股、代碼有誤、或當日無交易）`)
+        }
+    }
+
+    return { source: 'tpex', date: dateStr, count: resultData.length, data: resultData }
+}
+
+
+export default fetchTpexStock

package/src/fetchTwDataHoliday.mjs

@@ -0,0 +1,164 @@
+import get from 'lodash-es/get.js'
+import isestr from 'wsemi/src/isestr.mjs'
+import isearr from 'wsemi/src/isearr.mjs'
+import fetchWithRetry from './fetchWithRetry.mjs'
+import getOptFetch from './getOptFetch.mjs'
+
+
+//證交所開放資料平台之休市日期API
+let API_URL = 'https://openapi.twse.com.tw/v1/holidaySchedule/holidaySchedule'
+
+
+//本函數之預設抓取設定
+let DFLT = {
+    responseType: 'text',
+    timeout: 30000,
+    maxRetries: 10,
+    baseDelayMs: 5000,
+    maxDelayMs: 30000,
+    label: 'fetch-tw-data-holiday',
+}
+
+
+/**
+ * 民國日期YYYMMDD轉西元日期YYYYMMDD
+ *
+ * @param {String} rocDate 輸入民國日期字串，年份位數不限
+ * @returns {String} 回傳西元日期YYYYMMDD字串
+ */
+function rocToWestern(rocDate) {
+
+    let rocYear = parseInt(rocDate.substring(0, rocDate.length - 4), 10)
+    let mmdd = rocDate.substring(rocDate.length - 4)
+
+    return `${rocYear + 1911}${mmdd}`
+}
+
+
+/**
+ * 判斷條目是否為非假日條目
+ *
+ * 應排除者有二類：
+ * 交易日標記(「國曆新年開始交易日」「農曆春節前最後交易日」「農曆春節後開始交易日」)；
+ * 結算作業日(「市場無交易，僅辦理結算交割作業」)
+ *
+ * @param {Object} entry 輸入API回傳之單筆條目物件
+ * @returns {Boolean} 回傳是否為非假日條目之布林值
+ */
+function isNonHolidayEntry(entry) {
+
+    let name = String(get(entry, 'Name', ''))
+    let description = String(get(entry, 'Description', ''))
+
+    return /交易日/.test(name) ||
+        /市場無交易/.test(name) ||
+        /開始交易/.test(description) ||
+        /最後交易/.test(description)
+}
+
+
+/**
+ * 抓取台灣證券市場休市日期
+ *
+ * 由證交所開放資料平台取得當年度休市日期清單, 排除交易日標記與結算作業日, 並依日期去重與排序;
+ * 給定checkDate時另回傳該日是否為休市日
+ *
+ * @param {String} [checkDate] 輸入待查詢日期YYYYMMDD字串，非合法YYYYMMDD時略過單日比對
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.url='https://openapi.twse.com.tw/v1/holidaySchedule/holidaySchedule'] 輸入API網址字串，供測試或改指向鏡像時覆寫
+ * @param {Integer} [opt.timeout=30000] 輸入單次請求逾時毫秒整數，預設30000
+ * @param {Integer} [opt.maxRetries=10] 輸入最大重試次數整數，含初始共執行maxRetries+1次，預設10
+ * @param {Integer} [opt.baseDelayMs=5000] 輸入重試之線性退避基礎毫秒整數，預設5000
+ * @param {Integer} [opt.maxDelayMs=30000] 輸入重試之線性退避上限毫秒整數，預設30000
+ * @param {Boolean} [opt.showLog=true] 輸入是否顯示重試訊息布林值，預設true
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件{dataYear,totalHolidays,holidays}，有給checkDate時另含{checkDate,isHoliday,holidayName}，API回傳非JSON或空陣列時reject回傳錯誤物件
+ * @example
+ *
+ * import fetchTwDataHoliday from './src/fetchTwDataHoliday.mjs'
+ *
+ * let test = async () => {
+ *
+ *     let r = await fetchTwDataHoliday('20260101')
+ *     console.log(r.dataYear, r.totalHolidays, r.isHoliday, r.holidayName)
+ *     // => '2026' 15 true '中華民國開國紀念日'
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function fetchTwDataHoliday(checkDate, opt = {}) {
+
+    //url
+    let url = get(opt, 'url')
+    if (!isestr(url)) {
+        url = API_URL
+    }
+
+    //optFetch
+    let optFetch = getOptFetch(opt, DFLT)
+
+    //body
+    let body = await fetchWithRetry(url, optFetch)
+
+    //raw, API維護時可能回HTTP 200加HTML(非JSON), 產生文件記載之友善訊息而非裸SyntaxError
+    let raw = null
+    try {
+        raw = JSON.parse(body)
+    }
+    catch (err) {
+        throw new Error('API 回傳非 JSON 格式（可能為維護頁面或網路中介），請稍後再試')
+    }
+    if (!isearr(raw)) {
+        throw new Error('API 回傳空陣列或格式異常')
+    }
+
+    //holidays, 轉為結構化假日清單(排除交易日標記與結算作業日)
+    let holidays = raw
+        .filter((entry) => !isNonHolidayEntry(entry))
+        .map((entry) => {
+            return {
+                date: rocToWestern(get(entry, 'Date', '')),
+                rocDate: get(entry, 'Date', ''),
+                name: get(entry, 'Name', ''),
+                weekday: get(entry, 'Weekday', ''),
+                description: String(get(entry, 'Description', '') || '').replace(/<br\s*\/?>/gi, '').trim(),
+            }
+        })
+
+    //uniqueHolidays, 去重(同一天可能有多筆同名條目)
+    let seen = new Set()
+    let uniqueHolidays = holidays.filter((h) => {
+        if (seen.has(h.date)) {
+            return false
+        }
+        seen.add(h.date)
+        return true
+    })
+    uniqueHolidays.sort((a, b) => a.date.localeCompare(b.date))
+
+    //dataYear
+    let dataYear = uniqueHolidays.length > 0 ? uniqueHolidays[0].date.substring(0, 4) : null
+
+    //result
+    let result = {
+        dataYear,
+        totalHolidays: uniqueHolidays.length,
+        holidays: uniqueHolidays,
+    }
+
+    //checkDate為opt, 僅當為合法YYYYMMDD字串才做單日假日比對, 無效則略過(不誤標isHoliday)
+    if (isestr(checkDate) && /^\d{8}$/.test(checkDate)) {
+        result.checkDate = checkDate
+        let match = uniqueHolidays.find((h) => h.date === checkDate)
+        result.isHoliday = !!match
+        result.holidayName = match ? match.name : null
+    }
+
+    return result
+}
+
+
+export default fetchTwDataHoliday