w-dwdata-hub 1.0.0

package/src/fetchHackerNews.mjs

@@ -0,0 +1,117 @@
+import get from 'lodash-es/get.js'
+import isestr from 'wsemi/src/isestr.mjs'
+import isearr from 'wsemi/src/isearr.mjs'
+import ispint from 'wsemi/src/ispint.mjs'
+import cint from 'wsemi/src/cint.mjs'
+import fetchWithRetry from './fetchWithRetry.mjs'
+import getOptFetch from './getOptFetch.mjs'
+import toDatetimeUTC8 from './toDatetimeUTC8.mjs'
+
+
+//Hacker News官方Firebase API
+let API_BASE = 'https://hacker-news.firebaseio.com/v0'
+
+
+//本函數之預設抓取設定
+let DFLT = {
+    timeout: 30000,
+    maxRetries: 5,
+    baseDelayMs: 3000,
+    maxDelayMs: 15000,
+    label: 'fetch-hacker-news',
+}
+
+
+//預設取回篇數與取詳情之併發數
+let DEFAULT_LIMIT = 30
+let CONCURRENCY = 10
+
+
+/**
+ * 抓取Hacker News最新文章
+ *
+ * 先取newstories.json之ID清單, 再分批(每批10筆)取各篇詳情並轉為統一格式;
+ * 分批採Promise.allSettled, 單篇重試耗盡不會拖垮同批其他已成功文章;
+ * 僅保留type為story者, 無外部連結時以Hacker News站內討論頁網址替代
+ *
+ * @param {Integer} [limit=30] 輸入取回文章數量正整數，非正整數時改用預設值，預設30
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.apiBase='https://hacker-news.firebaseio.com/v0'] 輸入API根網址字串，供測試或改指向鏡像時覆寫
+ * @param {Integer} [opt.timeout=30000] 輸入單次請求逾時毫秒整數，預設30000
+ * @param {Integer} [opt.maxRetries=5] 輸入最大重試次數整數，含初始共執行maxRetries+1次，預設5
+ * @param {Integer} [opt.baseDelayMs=3000] 輸入重試之線性退避基礎毫秒整數，預設3000
+ * @param {Integer} [opt.maxDelayMs=15000] 輸入重試之線性退避上限毫秒整數，預設15000
+ * @param {Boolean} [opt.showLog=true] 輸入是否顯示重試訊息布林值，預設true
+ * @returns {Promise} 回傳Promise，resolve回傳文章物件陣列，各物件為{url,time,title,description,from}，抓取ID清單失敗時reject回傳錯誤物件
+ * @example
+ *
+ * import fetchHackerNews from './src/fetchHackerNews.mjs'
+ *
+ * let test = async () => {
+ *
+ *     let rs = await fetchHackerNews(5)
+ *     console.log(rs.length, rs[0])
+ *     // => 5 { url: 'https://...', time: '2026-08-07 09:02:03', title: '...', description: '', from: 'Hacker News' }
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function fetchHackerNews(limit = DEFAULT_LIMIT, opt = {}) {
+
+    //limit, 非正整數(如NaN或<=0)時改用預設值, 避免slice(0,NaN)靜默回傳空陣列
+    limit = ispint(limit) ? cint(limit) : DEFAULT_LIMIT
+
+    //apiBase
+    let apiBase = get(opt, 'apiBase')
+    if (!isestr(apiBase)) {
+        apiBase = API_BASE
+    }
+    apiBase = apiBase.replace(/\/+$/, '')
+
+    //optFetch
+    let optFetch = getOptFetch(opt, DFLT)
+
+    //ids, 取得最新文章ID列表
+    let ids = await fetchWithRetry(`${apiBase}/newstories.json`, optFetch)
+    if (!isearr(ids)) {
+        ids = []
+    }
+    let selected = ids.slice(0, limit)
+
+    //items, 批次取得文章詳情並控制併發數
+    let items = []
+    for (let i = 0; i < selected.length; i += CONCURRENCY) {
+        let batch = selected.slice(i, i + CONCURRENCY)
+
+        //allSettled, 單一item重試耗盡而reject時不丟失整批其他已成功之文章
+        let rs = await Promise.allSettled(batch.map((id) => {
+            return fetchWithRetry(`${apiBase}/item/${id}.json`, optFetch)
+        }))
+        for (let r of rs) {
+            if (r.status === 'fulfilled') {
+                items.push(r.value)
+            }
+        }
+
+    }
+
+    //轉換為統一格式
+    return items
+        .filter((item) => item && item.type === 'story')
+        .map((item) => {
+            return {
+                url: String(get(item, 'url', '') || `https://news.ycombinator.com/item?id=${get(item, 'id', '')}`).trim(),
+                time: toDatetimeUTC8(get(item, 'time', 0)),
+                title: String(get(item, 'title', '') || '').trim(),
+                description: '',
+                from: 'Hacker News',
+            }
+        })
+}
+
+
+export default fetchHackerNews

package/src/fetchMoneydj.mjs

@@ -0,0 +1,179 @@
+import * as cheerio from 'cheerio'
+import get from 'lodash-es/get.js'
+import isfun from 'wsemi/src/isfun.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import ispint from 'wsemi/src/ispint.mjs'
+import cint from 'wsemi/src/cint.mjs'
+import delay from 'wsemi/src/delay.mjs'
+import fetchWithRetry from './fetchWithRetry.mjs'
+import getOptFetch from './getOptFetch.mjs'
+
+
+//MoneyDJ台股新聞(MB06)列表頁, 頁碼接於index1之後
+let BASE_URL = 'https://www.moneydj.com/kmdj/news/newsreallist.aspx?a=mb06&index1='
+
+
+//本函數之預設抓取設定
+let DFLT = {
+    responseType: 'text',
+    timeout: 30000,
+    maxRetries: 10,
+    baseDelayMs: 5000,
+    maxDelayMs: 30000,
+    retryStatus: [403],
+    label: 'fetch-moneydj',
+}
+
+
+//預設抓取頁數
+let DEFAULT_TOTAL_PAGES = 50
+
+
+//頁間隨機延遲之下限與變動範圍毫秒
+let PAGE_DELAY_MIN_MS = 1000
+let PAGE_DELAY_RANGE_MS = 2000
+
+
+//列表頁時間欄位格式, 例如'08/07 09:02'、'09:02'、'昨 09:02'
+let REG_TIME = /^(\d{2}\/\d{2}\s+\d{2}:\d{2}|\d{2}:\d{2}|昨\s*\d{2}:\d{2})$/
+
+
+/**
+ * 抓取MoneyDJ台股新聞
+ *
+ * 逐頁抓取MoneyDJ台股新聞(MB06)列表, 頁間隨機延遲1至3秒以降低被封鎖風險;
+ * 單頁抓取失敗(重試耗盡)時記錄並跳過該頁, 不中斷整體抓取; 全部頁面皆0筆時拋出錯誤
+ *
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.baseUrl='https://www.moneydj.com/kmdj/news/newsreallist.aspx?a=mb06&index1='] 輸入列表頁網址前綴字串，頁碼會直接串接於後，供測試或改指向鏡像時覆寫
+ * @param {Integer} [opt.totalPages=50] 輸入要抓取的頁數正整數，預設50
+ * @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 {Integer} [opt.pageDelayMs] 輸入頁間延遲毫秒整數，未給時採隨機1000至3000毫秒
+ * @param {Function} [opt.onPageDone] 輸入每頁完成時之回呼函數，傳入(pageIndex,itemCount,totalPages)
+ * @param {Boolean} [opt.showLog=true] 輸入是否顯示過程訊息布林值，預設true
+ * @returns {Promise} 回傳Promise，resolve回傳新聞物件陣列，各物件為{time,title,link}，抓取到0筆時reject回傳錯誤物件
+ * @example
+ *
+ * import fetchMoneydj from './src/fetchMoneydj.mjs'
+ *
+ * let test = async () => {
+ *
+ *     let rs = await fetchMoneydj({ totalPages: 2 })
+ *     console.log(rs.length, rs[0])
+ *     // => 60 { time: '08/07 09:02', title: '...', link: 'https://www.moneydj.com/kmdj/news/...' }
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function fetchMoneydj(opt = {}) {
+
+    //baseUrl
+    let baseUrl = get(opt, 'baseUrl')
+    if (!isestr(baseUrl)) {
+        baseUrl = BASE_URL
+    }
+
+    //totalPages
+    let totalPages = get(opt, 'totalPages')
+    if (!ispint(totalPages)) {
+        totalPages = DEFAULT_TOTAL_PAGES
+    }
+    else {
+        totalPages = cint(totalPages)
+    }
+
+    //onPageDone
+    let onPageDone = get(opt, 'onPageDone')
+    if (!isfun(onPageDone)) {
+        onPageDone = () => {}
+    }
+
+    //optFetch
+    let optFetch = getOptFetch(opt, DFLT)
+    let showLog = optFetch.showLog
+
+    //pageDelayMs, 頁間隨機延遲毫秒
+    let pageDelayMs = get(opt, 'pageDelayMs')
+    if (!ispint(pageDelayMs) && pageDelayMs !== 0) {
+        pageDelayMs = null
+    }
+    else {
+        pageDelayMs = cint(pageDelayMs)
+    }
+
+    //domain, 由列表頁網址推得, 供補齊相對路徑連結
+    let domain = new URL(baseUrl).origin
+
+    //fetchPage
+    let fetchPage = async (pageIndex) => {
+
+        //html, MoneyDJ已確認使用UTF-8編碼(多次實測結果正確), 無需Big5解碼
+        let html = await fetchWithRetry(`${baseUrl}${pageIndex}`, { ...optFetch, label: `${DFLT.label} Page ${pageIndex}` })
+
+        //$
+        let $ = cheerio.load(html)
+
+        //newsItems
+        let newsItems = []
+        $('tr').each((i, el) => {
+
+            let $row = $(el)
+            let timeText = $row.find('td').eq(0).text().trim()
+            let $link = $row.find('td').eq(1).find('a')
+
+            if (timeText && REG_TIME.test(timeText) && $link.length > 0) {
+                let title = $link.attr('title') || $link.text().trim()
+                let linkRel = $link.attr('href')
+                if (linkRel) {
+                    let link = linkRel.startsWith('http') ? linkRel : domain + linkRel
+                    newsItems.push({ time: timeText, title, link })
+                }
+            }
+
+        })
+
+        return newsItems
+    }
+
+    let allNewsItems = []
+    for (let i = 1; i <= totalPages; i++) {
+
+        //items, 單頁失敗記錄並跳過, 不中斷整體抓取
+        let items = null
+        try {
+            items = await fetchPage(i)
+        }
+        catch (err) {
+            if (showLog) {
+                console.warn(`[Page ${i}] 抓取失敗，已跳過：${err.message}`)
+            }
+            continue
+        }
+        allNewsItems = allNewsItems.concat(items)
+
+        onPageDone(i, items.length, totalPages)
+
+        //頁間延遲, 未指定pageDelayMs時採隨機1至3秒以降低被封鎖風險
+        if (i < totalPages) {
+            await delay(pageDelayMs === null ? Math.floor(Math.random() * PAGE_DELAY_RANGE_MS) + PAGE_DELAY_MIN_MS : pageDelayMs)
+        }
+
+    }
+
+    //check, 0筆代表版型改變或selector失效
+    if (allNewsItems.length === 0) {
+        throw new Error('抓取到 0 筆新聞，可能是頁面結構改變或 selector 失效，請確認 MoneyDJ 頁面是否正常。')
+    }
+
+    return allNewsItems
+}
+
+
+export default fetchMoneydj

package/src/fetchMops.mjs

@@ -0,0 +1,313 @@
+import { chromium } from 'playwright'
+import get from 'lodash-es/get.js'
+import isbol from 'wsemi/src/isbol.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import isp0int from 'wsemi/src/isp0int.mjs'
+import cint from 'wsemi/src/cint.mjs'
+import delay from 'wsemi/src/delay.mjs'
+
+
+//公開資訊觀測站重大訊息頁與其查詢API
+let PAGE_URL = 'https://mops.twse.com.tw/mops/#/web/t146sb10'
+let API_URL = 'https://mops.twse.com.tw/mops/api/t146sb10'
+
+
+//預設值
+let DEFAULT_MAX_RETRIES = 10
+let DEFAULT_BASE_DELAY_MS = 5000
+let DEFAULT_MAX_DELAY_MS = 30000
+let LAUNCH_TIMEOUT_MS = 360000
+let GOTO_TIMEOUT_MS = 60000
+
+
+//目標市場別, marketKind為API查詢參數
+let MARKET_KINDS = [
+    { name: '上市', marketKind: 'sii' },
+    { name: '上櫃', marketKind: 'otc' },
+    { name: '興櫃', marketKind: 'rotc' },
+    { name: '公開發行', marketKind: 'pub' },
+]
+
+
+/**
+ * 組出單一市場別之API查詢payload
+ *
+ * @param {String} marketKind 輸入市場別字串，可為'sii'、'otc'、'rotc'、'pub'
+ * @returns {Object} 回傳API查詢payload物件
+ */
+function getPayload(marketKind) {
+    return {
+        scopeType: '2',
+        companyId: '',
+        dateType: '2',
+        firstDate: '',
+        lastDate: '',
+        marketKind,
+        announcementBasis: '0',
+        dateRangeType: '1',
+        announcementType: '1',
+        sort: '1',
+        encodeURIComponent: 1,
+        step: 1,
+        firstin: 1,
+        off: 1,
+    }
+}
+
+
+/**
+ * 於瀏覽器頁面內以fetch呼叫MOPS查詢API並自動重試
+ *
+ * 需於MOPS頁面context內發送請求(同源且帶站方cookie), 故採page.evaluate而非node端直接請求;
+ * 重試條件為HTTP 5xx、403、429或網路錯誤, application-level錯誤(如MOPS code 500)屬非暫時性故不重試
+ *
+ * @param {Object} page 輸入playwright之page物件
+ * @param {Object} target 輸入目標物件，內含name、marketKind、url與payload
+ * @param {Object} cfg 輸入已正規化之設定物件
+ * @returns {Promise} 回傳Promise，resolve回傳{json,raw}或{error,retryable}
+ */
+async function fetchTargetWithRetry(page, target, cfg) {
+
+    let data = null
+    for (let attempt = 1; attempt <= cfg.maxRetries + 1; attempt++) {
+
+        data = await page.evaluate(async (t) => {
+            try {
+
+                let response = await fetch(t.url, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(t.payload),
+                })
+                if (response.status >= 500 || response.status === 403 || response.status === 429) {
+                    return { error: `HTTP ${response.status}`, retryable: true }
+                }
+
+                let text = await response.text()
+                try {
+
+                    let json = JSON.parse(text)
+
+                    //驗證MOPS application-level狀態碼(HTTP 200不代表查詢成功)
+                    //實測契約: code=200「查詢成功」、code=406「查無相符資料」(正常空結果)、其餘(如500)為application-level錯誤
+                    let code = json && json.code
+                    if (code !== 200 && code !== 406) {
+                        //非成功且非「查無資料」→ application-level錯誤, 帶原始回應供除錯, 屬非暫時性故不重試
+                        return { error: `MOPS code ${code}: ${(json && json.message) || ''}`, json, raw: text.substring(0, 500), retryable: false }
+                    }
+
+                    return { json, raw: text.substring(0, 500) }
+                }
+                catch (e) {
+                    return { error: 'Parse Error', raw: text, retryable: false }
+                }
+
+            }
+            catch (err) {
+                return { error: err.toString(), retryable: true }
+            }
+        }, target)
+
+        if (!data.error) {
+            return data
+        }
+
+        let retryable = data.retryable !== false
+        let attemptsLeft = cfg.maxRetries + 1 - attempt
+        if (!retryable || attemptsLeft <= 0) {
+            return data //回傳錯誤結果, 由呼叫方處理
+        }
+
+        let ms = Math.min(cfg.baseDelayMs * attempt, cfg.maxDelayMs)
+        if (cfg.showLog) {
+            console.warn(`[${target.name}][Retry ${attempt}/${cfg.maxRetries}] ${data.error} — 等待 ${ms / 1000}s 後重試...`)
+        }
+        await delay(ms)
+
+    }
+
+    return data
+}
+
+
+/**
+ * 抓取公開資訊觀測站(MOPS)今日重大訊息
+ *
+ * 以playwright啟動本機Chrome(channel為'chrome', 可由環境變數CHROME_PATH指定執行檔)開啟MOPS重大訊息頁,
+ * 再於頁面context內逐一查詢上市、上櫃、興櫃與公開發行之今日重大訊息;
+ * 單一市場別失敗時記錄於該筆之error並續抓其餘市場別, 由hasError告知是否有失敗
+ *
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.pageUrl='https://mops.twse.com.tw/mops/#/web/t146sb10'] 輸入MOPS重大訊息頁網址字串，供測試或改指向鏡像時覆寫
+ * @param {String} [opt.apiUrl='https://mops.twse.com.tw/mops/api/t146sb10'] 輸入MOPS查詢API網址字串，供測試或改指向鏡像時覆寫
+ * @param {Integer} [opt.maxRetries=10] 輸入最大重試次數整數，含初始共執行maxRetries+1次，預設10
+ * @param {Boolean} [opt.showLog=true] 輸入是否顯示過程訊息布林值，預設true
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件{results,hasError}，results各筆為{market,marketKind,data,error,timestamp}，瀏覽器啟動失敗時reject回傳錯誤物件
+ * @example
+ *
+ * import fetchMops from './src/fetchMops.mjs'
+ *
+ * let test = async () => {
+ *
+ *     let r = await fetchMops()
+ *     console.log(r.hasError, r.results.length, r.results[0].market)
+ *     // => false 4 '上市'
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function fetchMops(opt = {}) {
+
+    //pageUrl
+    let pageUrl = get(opt, 'pageUrl')
+    if (!isestr(pageUrl)) {
+        pageUrl = PAGE_URL
+    }
+
+    //apiUrl
+    let apiUrl = get(opt, 'apiUrl')
+    if (!isestr(apiUrl)) {
+        apiUrl = API_URL
+    }
+
+    //maxRetries
+    let maxRetries = get(opt, 'maxRetries')
+    if (!isp0int(maxRetries)) {
+        maxRetries = DEFAULT_MAX_RETRIES
+    }
+    else {
+        maxRetries = cint(maxRetries)
+    }
+
+    //showLog
+    let showLog = get(opt, 'showLog')
+    if (!isbol(showLog)) {
+        showLog = true
+    }
+
+    //cfg
+    let cfg = {
+        maxRetries,
+        baseDelayMs: DEFAULT_BASE_DELAY_MS,
+        maxDelayMs: DEFAULT_MAX_DELAY_MS,
+        showLog,
+    }
+
+    //targets
+    let targets = MARKET_KINDS.map((v) => {
+        return {
+            name: v.name,
+            marketKind: v.marketKind,
+            url: apiUrl,
+            payload: getPayload(v.marketKind),
+        }
+    })
+
+    if (showLog) {
+        console.log('啟動瀏覽器...')
+    }
+
+    //browser, 帶重試之瀏覽器啟動
+    let browser = null
+    for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+        try {
+            browser = await chromium.launch({
+                headless: true,
+                //設定環境變數CHROME_PATH則用該路徑啟動瀏覽器
+                //未設定時為undefined, playwright會忽略executablePath改走channel為'chrome', 行為不變
+                executablePath: process.env.CHROME_PATH || undefined,
+                channel: 'chrome',
+                args: ['--no-sandbox', '--disable-setuid-sandbox'],
+                timeout: LAUNCH_TIMEOUT_MS,
+            })
+            break
+        }
+        catch (err) {
+            let attemptsLeft = maxRetries + 1 - attempt
+            if (attemptsLeft <= 0) {
+                throw new Error(`瀏覽器啟動失敗（已重試 ${maxRetries} 次）: ${err.message}`)
+            }
+            let ms = Math.min(DEFAULT_BASE_DELAY_MS * attempt, DEFAULT_MAX_DELAY_MS)
+            if (showLog) {
+                console.warn(`[browser.launch][Retry ${attempt}/${maxRetries}] ${err.message} — 等待 ${ms / 1000}s 後重試...`)
+            }
+            await delay(ms)
+        }
+    }
+
+    try {
+
+        let page = await browser.newPage()
+
+        //帶重試之頁面導航
+        if (showLog) {
+            console.log('前往 MOPS 重大訊息頁面 (t146sb10)...')
+        }
+        for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+            try {
+                await page.goto(pageUrl, { waitUntil: 'networkidle', timeout: GOTO_TIMEOUT_MS })
+                break
+            }
+            catch (err) {
+                let attemptsLeft = maxRetries + 1 - attempt
+                if (attemptsLeft <= 0) {
+                    throw err
+                }
+                let ms = Math.min(DEFAULT_BASE_DELAY_MS * attempt, DEFAULT_MAX_DELAY_MS)
+                if (showLog) {
+                    console.warn(`[page.goto][Retry ${attempt}/${maxRetries}] ${err.message} — 等待 ${ms / 1000}s 後重試...`)
+                }
+                await delay(ms)
+            }
+        }
+
+        await page.waitForTimeout(2000)
+
+        //results
+        let results = []
+        for (let target of targets) {
+
+            if (showLog) {
+                console.log(`正在抓取 [${target.name}] 資料...`)
+            }
+
+            let data = await fetchTargetWithRetry(page, target, cfg)
+
+            results.push({
+                market: target.name,
+                marketKind: target.marketKind,
+                data: data.json || data,
+                ...(data.error && { error: data.error }),
+                timestamp: new Date().toISOString(),
+            })
+
+            await page.waitForTimeout(1000)
+        }
+
+        if (showLog) {
+            let summary = results.map((r) => {
+                let resultData = get(r, 'data.result', get(r, 'data'))
+                let count = Array.isArray(resultData) ? resultData.length : 0
+                return `${r.market}: 取得 ${count} 筆資料`
+            })
+            console.log('抓取完成。摘要:', summary)
+        }
+
+        //hasError
+        let hasError = results.some((r) => r.error)
+
+        return { results, hasError }
+
+    }
+    finally {
+        await browser.close()
+    }
+}
+
+
+export { MARKET_KINDS, getPayload }
+export default fetchMops

package/src/fetchRSS.mjs

@@ -0,0 +1,88 @@
+import Parser from 'rss-parser'
+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 toDatetimeUTC8 from './toDatetimeUTC8.mjs'
+
+
+//本函數之預設抓取設定, 因YouTube等站台之RSS會回傳暫時性404故將404納入重試範圍
+let DFLT = {
+    responseType: 'text',
+    timeout: 30000,
+    maxRetries: 5,
+    baseDelayMs: 3000,
+    maxDelayMs: 15000,
+    retryStatus: [404],
+    label: 'fetch-rss',
+}
+
+
+/**
+ * 抓取RSS訂閱源
+ *
+ * 支援RSS與Atom, 並轉為統一格式, 時間欄位一律轉為UTC+8之'YYYY-MM-DD HH:mm:ss'字串;
+ * 因YouTube等站台之RSS會回傳暫時性404, 故404亦納入重試範圍
+ *
+ * @param {String} rssUrl 輸入RSS網址字串，須為http或https
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {Integer} [opt.timeout=30000] 輸入單次請求逾時毫秒整數，預設30000
+ * @param {Integer} [opt.maxRetries=5] 輸入最大重試次數整數，含初始共執行maxRetries+1次，預設5
+ * @param {Integer} [opt.baseDelayMs=3000] 輸入重試之線性退避基礎毫秒整數，預設3000
+ * @param {Integer} [opt.maxDelayMs=15000] 輸入重試之線性退避上限毫秒整數，預設15000
+ * @param {Boolean} [opt.showLog=true] 輸入是否顯示重試訊息布林值，預設true
+ * @returns {Promise} 回傳Promise，resolve回傳項目物件陣列，各物件為{url,time,title,description,from}，網址無效或抓取失敗時reject回傳錯誤物件
+ * @example
+ *
+ * import fetchRSS from './src/fetchRSS.mjs'
+ *
+ * let test = async () => {
+ *
+ *     let rs = await fetchRSS('https://www.ptt.cc/atom/Gossiping.xml')
+ *     console.log(rs.length, rs[0])
+ *     // => 20 { url: 'https://...', time: '2026-08-07 09:02:03', title: '...', description: '...', from: '...' }
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function fetchRSS(rssUrl, opt = {}) {
+
+    //check
+    if (!isestr(rssUrl) || !/^https?:\/\//i.test(rssUrl)) {
+        throw new Error('rssUrl 須為有效的 http/https RSS 網址')
+    }
+
+    //xml
+    let xml = await fetchWithRetry(rssUrl, getOptFetch(opt, DFLT))
+
+    //feed
+    let parser = new Parser()
+    let feed = await parser.parseString(xml)
+
+    //feedFrom
+    let feedFrom = String(get(feed, 'title', '') || '').trim()
+
+    //items
+    let items = get(feed, 'items')
+    if (!isearr(items)) {
+        items = []
+    }
+
+    return items.map((item) => {
+        return {
+            url: String(get(item, 'link', '') || '').trim(),
+            time: toDatetimeUTC8(get(item, 'isoDate', '') || get(item, 'pubDate', '')),
+            title: String(get(item, 'title', '') || '').trim(),
+            description: String(get(item, 'contentSnippet', '') || get(item, 'summary', '') || '').trim(),
+            from: String(get(item, 'creator', '') || feedFrom).trim(),
+        }
+    })
+}
+
+
+export default fetchRSS