dsh-plugin-show-me-data 0.1.0

package/src/sources/registry.js

@@ -0,0 +1,153 @@
+/**
+ * Adapter registry — the single extension point for data sources (docs/02 §5.2).
+ *
+ * Adding a source is one file plus one row in {@link ADAPTERS}; the contract
+ * suite walks this list, so a new adapter is covered automatically.
+ *
+ * @module sources/registry
+ */
+import * as ecb from './ecb.js'
+import * as eastmoneyMacro from './eastmoney-macro.js'
+import * as eastmoneyQuote from './eastmoney-quote.js'
+import * as fred from './fred.js'
+import * as quoteCascade from './quote-cascade.js'
+import * as sinaCn from './sina-cn.js'
+import * as sinaUs from './sina-us.js'
+import * as tencent from './tencent.js'
+import * as usTreasury from './us-treasury.js'
+import * as usTreasuryRates from './us-treasury-rates.js'
+import * as worldbank from './worldbank.js'
+import { SourceError } from '../core/types.js'
+
+/** Every registered adapter, in documentation order. */
+export const ADAPTERS = [fred, eastmoneyQuote, eastmoneyMacro, usTreasury, usTreasuryRates, worldbank, ecb, tencent, sinaCn, sinaUs, quoteCascade]
+
+/** @type {Map<string, any>} */
+const BY_ID = new Map(ADAPTERS.map((adapter) => [adapter.id, adapter]))
+
+/** Adapter ids that must exist for the plugin to be useful (docs/07 T3.1). */
+export const REQUIRED_ADAPTER_IDS = [
+  'fred',
+  'eastmoney-quote',
+  'eastmoney-macro',
+  'us-treasury',
+  'us-treasury-rates',
+  'worldbank',
+  'ecb',
+  'tencent',
+  'sina-cn',
+  'sina-us',
+  'quote',
+]
+
+/**
+ * Look one adapter up by id.
+ *
+ * @param {string} id - adapter id.
+ * @returns {any|undefined} adapter module.
+ */
+export function getAdapter(id) {
+  return BY_ID.get(id)
+}
+
+/**
+ * All registered adapter ids.
+ *
+ * @returns {string[]} adapter ids.
+ */
+export function adapterIds() {
+  return [...BY_ID.keys()]
+}
+
+/**
+ * Whether an adapter id is registered.
+ *
+ * @param {string} id - adapter id.
+ * @returns {boolean} registration flag.
+ */
+export function hasAdapter(id) {
+  return BY_ID.has(id)
+}
+
+/**
+ * Every adapter's declared capabilities, for the settings/health surface.
+ *
+ * @returns {Array<{ id: string, label: string, capabilities: any[] }>} capability list.
+ */
+export function listCapabilities() {
+  return ADAPTERS.map((adapter) => ({ id: adapter.id, label: adapter.label, capabilities: adapter.capabilities }))
+}
+
+/**
+ * Whether an adapter can re-sample its bars (day/week/month).
+ *
+ * Declared per adapter rather than inferred from the request: the Sina US index
+ * endpoint is daily-only and silently ignores a `klt` parameter, so offering a
+ * "weekly" button for it produced three identical charts — a control that looks
+ * like it works and does nothing. The panel only shows the control when this is
+ * true.
+ *
+ * @param {string} adapterId - adapter id.
+ * @returns {boolean} whether 'params.klt' changes the returned bars.
+ */
+export function supportsBarSize(adapterId) {
+  return BY_ID.get(adapterId)?.barSizes === true
+}
+
+/**
+ * The per-source fetch budget, when an adapter declares one.
+ *
+ * The default (docs/04 §8) is sized for a fast API. A source that is legitimate
+ * but slow — the World Bank's indicator endpoint answers in 0.4–14s from here —
+ * needs its own budget, otherwise "slow" is indistinguishable from "down" and the
+ * card shows a false failure.
+ *
+ * @param {string} adapterId - adapter id.
+ * @returns {number|undefined} budget in ms, or 'undefined' for the default.
+ */
+export function sourceTimeoutMs(adapterId) {
+  const declared = BY_ID.get(adapterId)?.timeoutMs
+  return typeof declared === 'number' && declared > 0 ? declared : undefined
+}
+
+/**
+ * Resolve a source reference for a catalog binding.
+ *
+ * @param {string} adapterId - adapter id.
+ * @param {string} seriesRef - series reference.
+ * @param {object} [params] - catalog params.
+ * @returns {{ url: string, apiUrl?: string, seriesRef: string, label: string }|undefined} source reference.
+ */
+export function resolveSourceRef(adapterId, seriesRef, params) {
+  const adapter = BY_ID.get(adapterId)
+  if (adapter === undefined) return undefined
+  return adapter.sourceRef(seriesRef, params)
+}
+
+/**
+ * Fetch a series through its adapter.
+ *
+ * @param {string} adapterId - adapter id.
+ * @param {{ seriesRef: string, range: object, params?: object, preset?: string }} req - request.
+ * @param {{ fetch: Function, clock: object, signal?: AbortSignal }} deps - injected dependencies.
+ * @returns {Promise<object>} normalized 'RawSeries'.
+ */
+export async function fetchViaAdapter(adapterId, req, deps) {
+  const adapter = BY_ID.get(adapterId)
+  if (adapter === undefined) {
+    const { SourceError } = await import('../core/types.js')
+    throw new SourceError({
+      kind: 'unsupported',
+      adapterId,
+      seriesRef: req.seriesRef,
+      detail: `no adapter registered under ${JSON.stringify(adapterId)}; known: ${adapterIds().join(', ')}`,
+    })
+  }
+  // Adapters that compose others (the quote cascade) receive the dispatcher and
+  // the sourceRef resolver; plain adapters ignore them.
+  return adapter.fetchSeries(req, {
+    ...deps,
+    fetchViaAdapter: (innerId, innerReq, innerDeps) => fetchViaAdapter(innerId, innerReq, innerDeps ?? deps),
+    resolveSourceRef,
+  })
+}

package/src/sources/sina-cn.js

@@ -0,0 +1,197 @@
+/**
+ * 新浪 A 股指数 adapter — daily history for mainland indices and bond indices.
+ *
+ * Used as the quote source for this deployment because 东方财富's quote host
+ * resets connections and 腾讯's kline host answers 501 from this network. The
+ * endpoint is the one behind Sina's own index pages and returns a JSONP array.
+ *
+ *     x([{ day: 2026-09-11, open: 3910.920, high: 3912.320, low: 3852.030, close: 3888.110 }])
+ *
+ * Traps this adapter contains:
+ * - the body is **JSONP**: a redirect prefix precedes the wrapper, so the
+ *   payload must be located by its parentheses rather than by an exact prefix;
+ * - an unknown symbol answers x(null), which must be an 'unsupported' error
+ *   rather than a crash on `.length`;
+ * - every field is a **string**; `close` is the value, `volume` is ignored;
+ * - 恒生指数 is *not* served by this endpoint (verified: `x(null)`), so `hkHSI`
+ *   is deliberately absent from {@link SYMBOLS}.
+ *
+ * @module sources/sina-cn
+ */
+import { SourceError } from '../core/types.js'
+import { withBar } from './ohlc.js'
+import { parseNumber } from '../core/stats/series.js'
+import { getText } from './http.js'
+
+/** @type {string} */
+export const id = 'sina-cn'
+
+/** @type {string} */
+export const label = '新浪财经·A股'
+
+/** @type {Array<{ kinds: string[], frequencies: string[] }>} */
+export const capabilities = [{ kinds: ['equity', 'bond'], frequencies: ['daily'] }]
+
+/**
+ * The symbols this adapter serves, each verified live.
+ *
+ * @type {Record<string, { name: string, page: string }>}
+ */
+export const SYMBOLS = {
+  sh000001: { name: '上证指数', page: 'https://finance.sina.com.cn/realstock/company/sh000001/nc.shtml' },
+  sz399001: { name: '深证成指', page: 'https://finance.sina.com.cn/realstock/company/sz399001/nc.shtml' },
+  sh000300: { name: '沪深 300', page: 'https://finance.sina.com.cn/realstock/company/sh000300/nc.shtml' },
+  sz399006: { name: '创业板指', page: 'https://finance.sina.com.cn/realstock/company/sz399006/nc.shtml' },
+  sh000012: { name: '上证国债指数', page: 'https://finance.sina.com.cn/realstock/company/sh000012/nc.shtml' },
+  sh000013: { name: '上证企债指数', page: 'https://finance.sina.com.cn/realstock/company/sh000013/nc.shtml' },
+  sh000015: { name: '上证红利指数', page: 'https://finance.sina.com.cn/realstock/company/sh000015/nc.shtml' },
+}
+
+/** Default bar count. */
+const DEFAULT_LIMIT = 1200
+
+/** Its endpoint takes a 'scale' in minutes, so day/week/month bars are all real. */
+export const barSizes = true
+
+/**
+ * Bar sizes ('scale', in minutes): 240 is one trading day, 1200 a week, 7200 a month.
+ *
+ * Sina accepts other values (5/15/30/60 minute bars); only the three the panel
+ * offers are listed here.
+ */
+export const SCALE_BY_SIZE = { day: 240, week: 1200, month: 7200 }
+
+/**
+ * Build the kline URL for one symbol.
+ *
+ * @param {string} seriesRef - Sina symbol, e.g. 'sh000001'.
+ * @param {{ count?: number, scale?: number }} [params] - catalog params.
+ * @returns {string} request URL.
+ */
+export function buildUrl(seriesRef, params = {}) {
+  const count = params.count ?? DEFAULT_LIMIT
+  const scale = params.scale ?? SCALE_BY_SIZE.day
+  return `https://quotes.sina.cn/cn/api/jsonp_v2.php/x/CN_MarketDataService.getKLineData?symbol=${encodeURIComponent(seriesRef)}&scale=${scale}&ma=no&datalen=${count}`
+}
+
+/**
+ * Source reference for one symbol.
+ *
+ * @param {string} seriesRef - Sina symbol.
+ * @returns {{ adapterId: string, url: string, apiUrl: string, seriesRef: string, label: string }} source reference.
+ */
+export function sourceRef(seriesRef) {
+  return {
+    adapterId: id,
+    url: SYMBOLS[seriesRef]?.page ?? 'https://finance.sina.com.cn/stock/',
+    apiUrl: buildUrl(seriesRef),
+    seriesRef,
+    label,
+  }
+}
+
+/**
+ * Strip the JSONP wrapper (tolerating a redirect prefix) and parse it.
+ *
+ * @param {string} body - response body.
+ * @param {string} seriesRef - symbol (for errors).
+ * @returns {any} parsed payload ('null' for an unknown symbol).
+ */
+export function parseJsonp(body, seriesRef) {
+  const text = String(body ?? '')
+  const start = text.indexOf('(')
+  const end = text.lastIndexOf(')')
+  if (start === -1 || end === -1 || end <= start) {
+    throw new SourceError({
+      kind: 'parse',
+      adapterId: id,
+      seriesRef,
+      detail: `response is not the expected JSONP wrapper (${text.slice(0, 60).replace(/\s+/g, ' ')})`,
+    })
+  }
+  try {
+    return JSON.parse(text.slice(start + 1, end))
+  } catch {
+    throw new SourceError({
+      kind: 'parse',
+      adapterId: id,
+      seriesRef,
+      detail: `the JSONP payload is not valid JSON (${text.slice(start + 1, start + 60).replace(/\s+/g, ' ')})`,
+    })
+  }
+}
+
+/**
+ * Parse a kline body into ascending daily bars (the close is 'v').
+ *
+ * @param {string} body - response body.
+ * @param {string} seriesRef - symbol.
+ * @returns {{ name: string, points: Array<{ t: string, v: number }> }} parsed series.
+ */
+export function parseKline(body, seriesRef) {
+  const payload = parseJsonp(body, seriesRef)
+  if (payload === null || payload === undefined) {
+    throw new SourceError({
+      kind: 'unsupported',
+      adapterId: id,
+      seriesRef,
+      detail: `the endpoint does not serve ${seriesRef} (answered null)`,
+    })
+  }
+  if (!Array.isArray(payload)) {
+    throw new SourceError({ kind: 'parse', adapterId: id, seriesRef, detail: 'the JSONP payload is not an array' })
+  }
+  if (payload.length === 0) {
+    throw new SourceError({ kind: 'empty', adapterId: id, seriesRef, detail: 'the symbol returned zero bars' })
+  }
+  const points = []
+  for (const row of payload) {
+    if (row === null || typeof row !== 'object') continue
+    const date = row.day
+    if (typeof date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(date)) continue
+    const value = parseNumber(row.close)
+    if (value === undefined) continue
+    // The endpoint returns a full A-share bar per trading day; the close is the
+    // observation and open/high/low ride along for the candle view.
+    points.push(withBar(
+      { t: date, v: value },
+      { o: parseNumber(row.open), h: parseNumber(row.high), l: parseNumber(row.low) },
+    ))
+  }
+  if (points.length === 0) {
+    throw new SourceError({ kind: 'empty', adapterId: id, seriesRef, detail: 'no usable bars after filtering' })
+  }
+  points.sort((a, b) => (a.t < b.t ? -1 : a.t > b.t ? 1 : 0))
+  return { name: SYMBOLS[seriesRef]?.name ?? seriesRef, points }
+}
+
+/**
+ * Fetch and normalize one index series.
+ *
+ * @param {{ seriesRef: string, params?: { count?: number } }} req - request.
+ * @param {{ fetch: Function, clock: { now: () => Date }, signal?: AbortSignal }} deps - injected dependencies.
+ * @returns {Promise<object>} normalized 'RawSeries'.
+ */
+export async function fetchSeries(req, deps) {
+  const { seriesRef, params } = req
+  if (SYMBOLS[seriesRef] === undefined) {
+    throw new SourceError({
+      kind: 'unsupported',
+      adapterId: id,
+      seriesRef,
+      detail: `symbol ${JSON.stringify(seriesRef)} is not one of the verified indices (${Object.keys(SYMBOLS).join(', ')})`,
+    })
+  }
+  const url = buildUrl(seriesRef, params ?? {})
+  const { body } = await getText({ fetch: deps.fetch, url, adapterId: id, seriesRef, signal: deps.signal })
+  const { name, points } = parseKline(body, seriesRef)
+  return {
+    adapterId: id,
+    seriesRef,
+    points,
+    meta: { name, unit: '点', freq: 'daily' },
+    fetchedAt: deps.clock.now().toISOString(),
+    sourceRef: sourceRef(seriesRef),
+    raw: { url, bars: points.length },
+  }
+}

package/src/sources/sina-us.js

@@ -0,0 +1,187 @@
+/**
+ * 新浪美股指数 adapter — daily history for the US equity indices.
+ *
+ * Used because 东方财富's quote host resets connections from this network and
+ * FRED's equity-index series are unreachable here. The endpoint is the same one
+ * Sina's own US index pages use, and it returns full daily history (2004 onward)
+ * for the four major US indices.
+ *
+ * Response is a JSONP wrapper around a plain array:
+ *
+ *     x([{"d":"2026-09-11","o":"52204.46","h":"52720.24","l":"52204.46","c":"52573.29", ...}])
+ *
+ * Traps this adapter contains:
+ * - the body is **JSONP**, not JSON: the wrapper must be stripped before parsing;
+ * - the payload is GBK-encoded in some mirrors, so the raw bytes are decoded
+ *   defensively and non-UTF-8 bytes are replaced rather than throwing;
+ * - 'c' (close) is a string, and the rows arrive ascending;
+ * - the numeric index symbols ('.N225', '.GDAXI', …) that look plausible return
+ *   an error for this endpoint, so only the verified set is allowed through.
+ *
+ * @module sources/sina-us
+ */
+import { SourceError } from '../core/types.js'
+import { parseNumber } from '../core/stats/series.js'
+import { getText } from './http.js'
+import { withBar } from './ohlc.js'
+
+/** @type {string} */
+export const id = 'sina-us'
+
+/** @type {string} */
+export const label = '新浪财经'
+
+/** @type {Array<{ kinds: string[], frequencies: string[] }>} */
+export const capabilities = [{ kinds: ['equity'], frequencies: ['daily'] }]
+
+/**
+ * Today's daily bars only: this endpoint has no resampling parameter and ignores
+ * one, so the panel must not offer a period switch for these series.
+ */
+export const barSizes = false
+
+/**
+ * The symbols this adapter serves, each verified live.
+ *
+ * @type {Record<string, { name: string, page: string }>}
+ */
+export const SYMBOLS = {
+  '.DJI': { name: '道琼斯工业指数', page: 'https://finance.sina.com.cn/stock/usstock/' },
+  '.IXIC': { name: '纳斯达克综合指数', page: 'https://finance.sina.com.cn/stock/usstock/' },
+  '.INX': { name: '标普 500', page: 'https://finance.sina.com.cn/stock/usstock/' },
+  '.NDX': { name: '纳斯达克 100', page: 'https://finance.sina.com.cn/stock/usstock/' },
+}
+
+/**
+ * Build the JSONP URL for one symbol.
+ *
+ * @param {string} seriesRef - Sina US symbol, e.g. '.DJI'.
+ * @returns {string} request URL.
+ */
+export function buildUrl(seriesRef) {
+  return `https://stock.finance.sina.com.cn/usstock/api/jsonp.php/x/US_MinKService.getDailyK?symbol=${encodeURIComponent(seriesRef)}&___qn=3`
+}
+
+/**
+ * Source reference for one symbol.
+ *
+ * @param {string} seriesRef - Sina US symbol.
+ * @returns {{ adapterId: string, url: string, apiUrl: string, seriesRef: string, label: string }} source reference.
+ */
+export function sourceRef(seriesRef) {
+  const entry = SYMBOLS[seriesRef]
+  return {
+    adapterId: id,
+    url: entry?.page ?? 'https://finance.sina.com.cn/stock/usstock/',
+    apiUrl: buildUrl(seriesRef),
+    seriesRef,
+    label,
+  }
+}
+
+/**
+ * Strip the JSONP wrapper and parse the array.
+ *
+ * @param {string} body - response body.
+ * @param {string} seriesRef - symbol (for errors).
+ * @returns {any[]} parsed rows.
+ */
+export function parseJsonp(body, seriesRef) {
+  const text = String(body ?? '')
+  const start = text.indexOf('(')
+  const end = text.lastIndexOf(')')
+  if (start === -1 || end === -1 || end <= start) {
+    // A wrapper-less body is accepted too: some mirrors answer with bare JSON.
+    try {
+      const parsed = JSON.parse(text)
+      if (Array.isArray(parsed)) return parsed
+    } catch {
+      // fall through to the classified error
+    }
+    throw new SourceError({
+      kind: 'parse',
+      adapterId: id,
+      seriesRef,
+      detail: `response is not the expected JSONP wrapper (${text.slice(0, 60).replace(/\s+/g, ' ')})`,
+    })
+  }
+  const inner = text.slice(start + 1, end)
+  try {
+    const parsed = JSON.parse(inner)
+    if (!Array.isArray(parsed)) {
+      throw new SourceError({ kind: 'parse', adapterId: id, seriesRef, detail: 'the JSONP payload is not an array' })
+    }
+    return parsed
+  } catch (error) {
+    if (error instanceof SourceError) throw error
+    throw new SourceError({
+      kind: 'parse',
+      adapterId: id,
+      seriesRef,
+      detail: `the JSONP payload is not valid JSON (${String(inner).slice(0, 60).replace(/\s+/g, ' ')})`,
+    })
+  }
+}
+
+/**
+ * Parse a US daily kline body into ascending closes.
+ *
+ * @param {string} body - response body.
+ * @param {string} seriesRef - symbol.
+ * @returns {{ name: string, points: Array<{ t: string, v: number }> }} parsed series.
+ */
+export function parseDailyK(body, seriesRef) {
+  const rows = parseJsonp(body, seriesRef)
+  if (rows.length === 0) {
+    throw new SourceError({ kind: 'empty', adapterId: id, seriesRef, detail: 'the symbol returned zero rows' })
+  }
+  const points = []
+  for (const row of rows) {
+    if (row === null || typeof row !== 'object') continue
+    const date = row.d
+    if (typeof date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(date)) continue
+    const value = parseNumber(row.c)
+    if (value === undefined) continue
+    // The endpoint returns a full bar per day; the close is the observation and
+    // open/high/low are carried for the candlestick view. An incoherent bar (the
+    // live payload has one) is dropped here rather than forwarded: the close
+    // survives, the impossible candle never reaches the chart.
+    points.push(withBar({ t: date, v: value }, { o: parseNumber(row.o), h: parseNumber(row.h), l: parseNumber(row.l) }))
+  }
+  if (points.length === 0) {
+    throw new SourceError({ kind: 'empty', adapterId: id, seriesRef, detail: 'no usable rows after filtering' })
+  }
+  points.sort((a, b) => (a.t < b.t ? -1 : a.t > b.t ? 1 : 0))
+  return { name: SYMBOLS[seriesRef]?.name ?? seriesRef, points }
+}
+
+/**
+ * Fetch and normalize one US index series.
+ *
+ * @param {{ seriesRef: string, params?: object }} req - request.
+ * @param {{ fetch: Function, clock: { now: () => Date }, signal?: AbortSignal }} deps - injected dependencies.
+ * @returns {Promise<object>} normalized 'RawSeries'.
+ */
+export async function fetchSeries(req, deps) {
+  const { seriesRef } = req
+  if (SYMBOLS[seriesRef] === undefined) {
+    throw new SourceError({
+      kind: 'unsupported',
+      adapterId: id,
+      seriesRef,
+      detail: `symbol ${JSON.stringify(seriesRef)} is not one of the verified indices (${Object.keys(SYMBOLS).join(', ')})`,
+    })
+  }
+  const url = buildUrl(seriesRef)
+  const { body } = await getText({ fetch: deps.fetch, url, adapterId: id, seriesRef, signal: deps.signal })
+  const { name, points } = parseDailyK(body, seriesRef)
+  return {
+    adapterId: id,
+    seriesRef,
+    points,
+    meta: { name, unit: '点', freq: 'daily' },
+    fetchedAt: deps.clock.now().toISOString(),
+    sourceRef: sourceRef(seriesRef),
+    raw: { url, rows: points.length },
+  }
+}

package/src/sources/tencent.js

@@ -0,0 +1,158 @@
+/**
+ * 腾讯行情 adapter — daily kline for Chinese, Hong Kong and bond indices.
+ *
+ * Used as the quote source for this deployment because 东方财富's 'push2his'
+ * host resets connections from this network (its sibling 'datacenter-web' host
+ * works, so it is host-specific blocking rather than a credential problem).
+ *
+ * Response shape (verified live):
+ *
+ *     {"code":0,"data":{"sh000001":{"day":[["2026-09-11","3910.920","3888.110","3912.320","3852.030","579123145.000"]],"qt":{...}}}}
+ *
+ * Trap this adapter contains: within a 'day' row the column order is
+ * '[date, open, close, high, low, volume]' — **close is the third column**, which
+ * is not the order most vendors use. A test pins it against a recorded fixture
+ * whose values were checked against the published close.
+ *
+ * @module sources/tencent
+ */
+import { SourceError } from '../core/types.js'
+import { parseNumber } from '../core/stats/series.js'
+import { getText } from './http.js'
+
+/** @type {string} */
+export const id = 'tencent'
+
+/** @type {string} */
+export const label = '腾讯行情'
+
+/** @type {Array<{ kinds: string[], frequencies: string[] }>} */
+export const capabilities = [{ kinds: ['equity', 'bond'], frequencies: ['daily'] }]
+
+/** Index of the close inside a kline row: '[date, open, close, high, low, volume]'. */
+export const CLOSE_INDEX = 2
+
+/** Default bar count; ~6 years of trading days. */
+const DEFAULT_LIMIT = 1600
+
+/**
+ * Build the kline URL for one symbol.
+ *
+ * @param {string} seriesRef - Tencent symbol, e.g. 'sh000001'.
+ * @param {{ count?: number }} [params] - catalog params.
+ * @returns {string} request URL.
+ */
+export function buildUrl(seriesRef, params = {}) {
+  const count = params.count ?? DEFAULT_LIMIT
+  return `https://web.ifzq.gtimg.cn/appstock/app/fqkline/get?param=${encodeURIComponent(seriesRef)},day,,,${count},qfq`
+}
+
+/**
+ * Human landing page for a symbol.
+ *
+ * @param {string} seriesRef - Tencent symbol.
+ * @returns {string} page URL.
+ */
+export function pageUrl(seriesRef) {
+  if (seriesRef.startsWith('hk')) return 'https://gu.qq.com/hkHSI'
+  if (seriesRef.startsWith('sh') || seriesRef.startsWith('sz')) return `https://gu.qq.com/${seriesRef}/zs`
+  return 'https://gu.qq.com/'
+}
+
+/**
+ * Source reference for one symbol.
+ *
+ * @param {string} seriesRef - Tencent symbol.
+ * @returns {{ adapterId: string, url: string, apiUrl: string, seriesRef: string, label: string }} source reference.
+ */
+export function sourceRef(seriesRef) {
+  return { adapterId: id, url: pageUrl(seriesRef), apiUrl: buildUrl(seriesRef), seriesRef, label }
+}
+
+/**
+ * Parse a kline payload into ascending close prices.
+ *
+ * @param {string} body - response body.
+ * @param {string} seriesRef - symbol (for errors).
+ * @returns {{ name: string|undefined, points: Array<{ t: string, v: number }> }} parsed series.
+ */
+export function parseKline(body, seriesRef) {
+  let payload
+  try {
+    payload = JSON.parse(body)
+  } catch {
+    throw new SourceError({
+      kind: 'parse',
+      adapterId: id,
+      seriesRef,
+      detail: `response is not JSON (${String(body).slice(0, 60).replace(/\s+/g, ' ')})`,
+    })
+  }
+  if (payload === null || typeof payload !== 'object') {
+    throw new SourceError({ kind: 'parse', adapterId: id, seriesRef, detail: 'response is not a JSON object' })
+  }
+  if (payload.code !== 0) {
+    throw new SourceError({
+      kind: 'unsupported',
+      adapterId: id,
+      seriesRef,
+      detail: `upstream rejected the symbol (code=${payload.code}, msg=${payload.msg ?? ''})`,
+    })
+  }
+  const node = payload.data?.[seriesRef]
+  if (node === null || node === undefined) {
+    throw new SourceError({ kind: 'unsupported', adapterId: id, seriesRef, detail: `no data node for ${seriesRef}` })
+  }
+  const rows = node.qfqday ?? node.day
+  if (!Array.isArray(rows)) {
+    throw new SourceError({ kind: 'parse', adapterId: id, seriesRef, detail: 'the kline list is missing from the response' })
+  }
+  if (rows.length === 0) {
+    throw new SourceError({ kind: 'empty', adapterId: id, seriesRef, detail: 'the symbol returned zero bars' })
+  }
+  const points = []
+  for (const row of rows) {
+    if (!Array.isArray(row) || row.length <= CLOSE_INDEX) {
+      throw new SourceError({
+        kind: 'parse',
+        adapterId: id,
+        seriesRef,
+        detail: `a kline row has ${Array.isArray(row) ? row.length : 'no'} columns; expected at least ${CLOSE_INDEX + 1}`,
+      })
+    }
+    const date = String(row[0])
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) continue
+    const value = parseNumber(row[CLOSE_INDEX])
+    if (value === undefined) continue
+    points.push({ t: date, v: value })
+  }
+  if (points.length === 0) {
+    throw new SourceError({ kind: 'empty', adapterId: id, seriesRef, detail: 'no usable bars after filtering' })
+  }
+  points.sort((a, b) => (a.t < b.t ? -1 : a.t > b.t ? 1 : 0))
+  const name = Array.isArray(node.qt?.[seriesRef]) ? String(node.qt[seriesRef][1] ?? '') : undefined
+  return { name: name === '' ? undefined : name, points }
+}
+
+/**
+ * Fetch and normalize one index series.
+ *
+ * @param {{ seriesRef: string, params?: { count?: number } }} req - request.
+ * @param {{ fetch: Function, clock: { now: () => Date }, signal?: AbortSignal }} deps - injected dependencies.
+ * @returns {Promise<object>} normalized 'RawSeries'.
+ */
+export async function fetchSeries(req, deps) {
+  const { seriesRef, params } = req
+  const url = buildUrl(seriesRef, params ?? {})
+  const { body } = await getText({ fetch: deps.fetch, url, adapterId: id, seriesRef, signal: deps.signal })
+  const { name, points } = parseKline(body, seriesRef)
+  return {
+    adapterId: id,
+    seriesRef,
+    points,
+    meta: { name: name ?? seriesRef, unit: '点', freq: 'daily' },
+    fetchedAt: deps.clock.now().toISOString(),
+    sourceRef: sourceRef(seriesRef),
+    raw: { url, bars: points.length },
+  }
+}