dsh-plugin-show-me-data 0.1.0

package/src/sources/us-treasury-rates.js

@@ -0,0 +1,275 @@
+/**
+ * 美国财政部「每日国债收益率曲线」adapter.
+ *
+ * This is the **official publisher** of the US Treasury constant-maturity
+ * yields that FRED's 'DGS*' series republish, so it is a drop-in replacement
+ * when FRED is unreachable (this deployment's egress IP is blocked by its edge
+ * WAF). One CSV per calendar year contains every tenor, so a single request can
+ * serve all of the rate indicators.
+ *
+ * Response shape (verified live):
+ *
+ *     Date,"1 Mo","1.5 Month","2 Mo","3 Mo","4 Mo","6 Mo","1 Yr","2 Yr","3 Yr","5 Yr","7 Yr","10 Yr","20 Yr","30 Yr"
+ *     09/11/2026,3.93,3.99,4.05,4.07,4.15,4.12,4.35,4.63,4.69,4.78,4.87,4.96,5.38,5.35
+ *
+ * Traps this adapter contains:
+ * - dates are 'MM/DD/YYYY' and rows arrive **newest first**;
+ * - non-trading days simply have no row;
+ * - a tenor can be an empty string on days the Treasury did not publish it.
+ *
+ * @module sources/us-treasury-rates
+ */
+import { SourceError } from '../core/types.js'
+import { parseNumber } from '../core/stats/series.js'
+import { getText } from './http.js'
+
+/** @type {string} */
+export const id = 'us-treasury-rates'
+
+/** @type {string} */
+export const label = '美国财政部·收益率曲线'
+
+/** @type {Array<{ kinds: string[], frequencies: string[] }>} */
+export const capabilities = [{ kinds: ['rates', 'bond'], frequencies: ['daily'] }]
+
+/** Landing page for the dataset. */
+const DATASET_PAGE = 'https://home.treasury.gov/resource-center/data-chart-center/interest-rates/TextView?type=daily_treasury_yield_curve'
+
+/** The tenor column names, exactly as the CSV spells them. */
+export const TENORS = [
+  '1 Mo',
+  '1.5 Month',
+  '2 Mo',
+  '3 Mo',
+  '4 Mo',
+  '6 Mo',
+  '1 Yr',
+  '2 Yr',
+  '3 Yr',
+  '5 Yr',
+  '7 Yr',
+  '10 Yr',
+  '20 Yr',
+  '30 Yr',
+]
+
+/** Tenor labels → the catalog's 'params.tenor' spelling. */
+export const TENOR_ALIASES = {
+  '1m': '1 Mo',
+  '1mo': '1 Mo',
+  '3m': '3 Mo',
+  '6m': '6 Mo',
+  '1y': '1 Yr',
+  '2y': '2 Yr',
+  '3y': '3 Yr',
+  '5y': '5 Yr',
+  '7y': '7 Yr',
+  '10y': '10 Yr',
+  '20y': '20 Yr',
+  '30y': '30 Yr',
+}
+
+/**
+ * Resolve a 'params.tenor' value to the CSV column name.
+ *
+ * @param {string|undefined} tenor - catalog tenor (e.g. '10y').
+ * @returns {string} CSV column name.
+ */
+export function resolveTenor(tenor) {
+  if (typeof tenor !== 'string' || tenor === '') {
+    // A missing or unknown tenor is a *binding* mistake, not a data-shape
+    // problem: it can never succeed on retry, so it is classified `unsupported`.
+    throw new SourceError({
+      kind: 'unsupported',
+      adapterId: id,
+      seriesRef: 'daily_treasury_yield_curve',
+      detail: `params.tenor is required (one of ${Object.keys(TENOR_ALIASES).join(', ')})`,
+    })
+  }
+  const direct = TENORS.find((entry) => entry.toLowerCase() === tenor.toLowerCase())
+  if (direct !== undefined) return direct
+  const alias = TENOR_ALIASES[tenor.toLowerCase()]
+  if (alias !== undefined) return alias
+  throw new SourceError({
+    kind: 'unsupported',
+    adapterId: id,
+    seriesRef: 'daily_treasury_yield_curve',
+    detail: `unknown tenor ${JSON.stringify(tenor)}; known: ${Object.keys(TENOR_ALIASES).join(', ')}`,
+  })
+}
+
+/**
+ * Build the CSV URL for one calendar year.
+ *
+ * @param {number} year - calendar year.
+ * @returns {string} request URL.
+ */
+export function buildUrl(year) {
+  return (
+    'https://home.treasury.gov/resource-center/data-chart-center/interest-rates/daily-treasury-rates.csv/' +
+    `${year}/all?type=daily_treasury_yield_curve&field_tdr_date_value=${year}&page&_format=csv`
+  )
+}
+
+/**
+ * Source reference for one tenor.
+ *
+ * @param {string} seriesRef - dataset name ('daily_treasury_yield_curve').
+ * @param {{ tenor?: string }} [params] - catalog params.
+ * @returns {{ adapterId: string, url: string, apiUrl: string, seriesRef: string, label: string }} source reference.
+ */
+export function sourceRef(seriesRef, params = {}) {
+  const tenor = params.tenor === undefined ? '10y' : String(params.tenor)
+  return {
+    adapterId: id,
+    url: DATASET_PAGE,
+    apiUrl: buildUrl(2026),
+    seriesRef: `${seriesRef}#${tenor}`,
+    label,
+  }
+}
+
+/**
+ * Split one CSV line, honouring quoted fields.
+ *
+ * @param {string} line - CSV line.
+ * @returns {string[]} fields.
+ */
+export function splitCsvLine(line) {
+  const fields = []
+  let current = ''
+  let quoted = false
+  for (let i = 0; i < line.length; i += 1) {
+    const char = line[i]
+    if (quoted) {
+      if (char === '"') {
+        if (line[i + 1] === '"') {
+          current += '"'
+          i += 1
+        } else quoted = false
+      } else current += char
+    } else if (char === '"') {
+      quoted = true
+    } else if (char === ',') {
+      fields.push(current)
+      current = ''
+    } else current += char
+  }
+  fields.push(current)
+  return fields.map((field) => field.trim())
+}
+
+/**
+ * Convert 'MM/DD/YYYY' into 'YYYY-MM-DD'.
+ *
+ * @param {string} value - raw date.
+ * @returns {string|undefined} normalized date.
+ */
+export function normalizeDate(value) {
+  const match = /^(\d{2})\/(\d{2})\/(\d{4})$/.exec(String(value ?? '').trim())
+  if (match === null) return undefined
+  const [, month, day, year] = match
+  return `${year}-${month}-${day}`
+}
+
+/**
+ * Parse one year's CSV into ascending points for one tenor.
+ *
+ * @param {string} body - CSV text.
+ * @param {string} column - tenor column name.
+ * @param {{ seriesRef?: string }} [options] - options.
+ * @returns {Array<{ t: string, v: number }>} ascending points.
+ */
+export function parseCurve(body, column, { seriesRef = 'daily_treasury_yield_curve' } = {}) {
+  const lines = String(body ?? '')
+    .trim()
+    .split(/\r?\n/)
+    .filter((line) => line.trim() !== '')
+  if (lines.length === 0) {
+    throw new SourceError({ kind: 'empty', adapterId: id, seriesRef, detail: 'the CSV body is empty' })
+  }
+  const header = splitCsvLine(lines[0])
+  const index = header.indexOf(column)
+  if (index === -1) {
+    throw new SourceError({
+      kind: 'parse',
+      adapterId: id,
+      seriesRef,
+      detail: `column ${JSON.stringify(column)} is absent; header has ${header.join(' | ')}`,
+    })
+  }
+  const dateIndex = header.findIndex((entry) => entry.toLowerCase() === 'date')
+  if (dateIndex === -1) {
+    throw new SourceError({ kind: 'parse', adapterId: id, seriesRef, detail: 'the header has no Date column' })
+  }
+
+  const points = []
+  for (const line of lines.slice(1)) {
+    const fields = splitCsvLine(line)
+    const date = normalizeDate(fields[dateIndex])
+    if (date === undefined) continue
+    const value = parseNumber(fields[index])
+    if (value === undefined) continue // an unpublished tenor is missing, not zero
+    points.push({ t: date, v: value })
+  }
+  if (points.length === 0) {
+    throw new SourceError({
+      kind: 'empty',
+      adapterId: id,
+      seriesRef,
+      detail: `no usable observations for ${column}`,
+    })
+  }
+  // The publisher lists newest first; every statistic downstream needs ascending.
+  points.sort((a, b) => (a.t < b.t ? -1 : a.t > b.t ? 1 : 0))
+  return points
+}
+
+/**
+ * Fetch and normalize one tenor's series.
+ *
+ * @param {{ seriesRef: string, params?: { tenor?: string }, range?: { to?: string } }} 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 column = resolveTenor(params?.tenor)
+  // Three calendar years cover every range preset (5Y/Max fall back to the
+  // oldest year available) without downloading the full archive.
+  const endYear = Number(String(req.range?.to ?? '').slice(0, 4))
+  const currentYear = Number.isInteger(endYear) && endYear > 1980 ? endYear : deps.clock.now().getUTCFullYear()
+  const years = [currentYear, currentYear - 1, currentYear - 2]
+  const bodies = await Promise.all(
+    years.map(async (year) => {
+      const { body } = await getText({
+        fetch: deps.fetch,
+        url: buildUrl(year),
+        adapterId: id,
+        seriesRef,
+        signal: deps.signal,
+        allowHttpError: true,
+      })
+      return body
+    }),
+  )
+  const merged = new Map()
+  for (const body of bodies) {
+    for (const point of parseCurve(body, column, { seriesRef })) merged.set(point.t, point.v)
+  }
+  const points = [...merged.entries()]
+    .map(([t, v]) => ({ t, v }))
+    .sort((a, b) => (a.t < b.t ? -1 : a.t > b.t ? 1 : 0))
+  if (points.length === 0) {
+    throw new SourceError({ kind: 'empty', adapterId: id, seriesRef, detail: `no observations for ${column} in ${years.join('/')}` })
+  }
+  return {
+    adapterId: id,
+    seriesRef,
+    points,
+    meta: { name: `US Treasury ${column}`, unit: '%', freq: 'daily' },
+    fetchedAt: deps.clock.now().toISOString(),
+    sourceRef: sourceRef(seriesRef, params),
+    raw: { years, column, points: points.length },
+  }
+}

package/src/sources/us-treasury.js

@@ -0,0 +1,196 @@
+/**
+ * 美国财政部 fiscaldata adapter (docs/04 §4).
+ *
+ * The response is a JSON envelope whose 'data' holds one row per
+ * 'security_desc' **per month**, and every numeric field is a *string* that may
+ * be empty. Without a 'filter', a series mixes Bills/Notes/Bonds/TIPS together —
+ * so the catalog passes 'params.filter' for a single security type.
+ *
+ * @module sources/us-treasury
+ */
+import { SourceError } from '../core/types.js'
+import { parseNumber } from '../core/stats/series.js'
+import { getText, parseJson } from './http.js'
+
+/** @type {string} */
+export const id = 'us-treasury'
+
+/** @type {string} */
+export const label = '美国财政部'
+
+/** @type {Array<{ kinds: string[], frequencies: string[] }>} */
+export const capabilities = [{ kinds: ['rates', 'fiscal'], frequencies: ['monthly'] }]
+
+/** Dataset endpoints this adapter serves. */
+export const DATASETS = {
+  avg_interest_rates: 'v2/accounting/od/avg_interest_rates',
+}
+
+/** Field holding the observation date. */
+export const DATE_FIELD = 'record_date'
+
+/**
+ * Build a fiscaldata URL.
+ *
+ * @param {string} dataset - dataset key (see {@link DATASETS}).
+ * @param {{ filter?: string, pageSize?: number, sort?: string }} [options] - query options.
+ * @returns {string} request URL.
+ */
+export function buildUrl(dataset, { filter, pageSize = 500, sort = `-${DATE_FIELD}` } = {}) {
+  const path = DATASETS[dataset]
+  if (path === undefined) {
+    throw new SourceError({
+      kind: 'unsupported',
+      adapterId: id,
+      seriesRef: dataset,
+      detail: `unknown fiscaldata dataset ${JSON.stringify(dataset)}; known: ${Object.keys(DATASETS).join(', ')}`,
+    })
+  }
+  const query = [`page[size]=${pageSize}`, `sort=${sort}`]
+  // fiscaldata expects the filter expression URL-encoded (`:` → `%3A`, space → `%20`).
+  if (filter) query.push(`filter=${encodeURIComponent(filter)}`)
+  return `https://api.fiscaldata.treasury.gov/services/api/fiscal_service/${path}?${query.join('&')}`
+}
+
+/**
+ * Dataset landing page plus the API URL.
+ *
+ * @param {string} seriesRef - dataset key.
+ * @param {{ filter?: string, valueField?: string }} [params] - catalog params.
+ * @returns {{ adapterId: string, url: string, apiUrl: string, seriesRef: string, label: string }} source reference.
+ */
+export function sourceRef(seriesRef, params = {}) {
+  const valueField = params.valueField ?? 'avg_interest_rate_amt'
+  // Provenance must never throw: an unknown dataset still has to produce a
+  // clickable landing page (the fetch path is where the id is rejected).
+  const apiUrl = DATASETS[seriesRef] === undefined
+    ? 'https://fiscaldata.treasury.gov/datasets/'
+    : buildUrl(seriesRef, { filter: params.filter })
+  return {
+    adapterId: id,
+    url: 'https://fiscaldata.treasury.gov/datasets/average-interest-rates-treasury-securities/',
+    apiUrl,
+    seriesRef: params.filter ? `${seriesRef}#${params.filter}` : `${seriesRef}#${valueField}`,
+    label,
+  }
+}
+
+/**
+ * Parse a fiscaldata payload.
+ *
+ * @param {string} body - response body.
+ * @param {string} seriesRef - dataset key (for errors).
+ * @param {{ valueField?: string }} [params] - which numeric column to read.
+ * @returns {{ name: string, points: Array<{ t: string, v: number }> }} parsed series.
+ */
+export function parseDataset(body, seriesRef, params = {}) {
+  const valueField = params.valueField ?? 'avg_interest_rate_amt'
+  const payload = parseJson(body, id, seriesRef)
+  if (payload === null || typeof payload !== 'object' || !Array.isArray(payload.data)) {
+    throw new SourceError({
+      kind: 'parse',
+      adapterId: id,
+      seriesRef,
+      detail: 'response has no `data` array',
+    })
+  }
+  if (payload.data.length === 0) {
+    throw new SourceError({ kind: 'empty', adapterId: id, seriesRef, detail: 'the dataset returned zero rows' })
+  }
+  const points = []
+  let sawField = false
+  const byDate = new Map()
+  for (const row of payload.data) {
+    if (row === null || typeof row !== 'object') continue
+    if (valueField in row) sawField = true
+    const date = row[DATE_FIELD]
+    if (typeof date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(date)) continue
+    const value = parseNumber(row[valueField])
+    if (value === undefined) continue
+    // One row per security type: keep the last read for a date so a filtered
+    // series is exact and an unfiltered one is at least deterministic.
+    byDate.set(date, value)
+  }
+  if (!sawField) {
+    throw new SourceError({
+      kind: 'parse',
+      adapterId: id,
+      seriesRef,
+      detail: `field ${valueField} is absent from the dataset; available: ${Object.keys(payload.data[0]).slice(0, 10).join(', ')}`,
+    })
+  }
+  for (const [t, v] of byDate) points.push({ t, v })
+  if (points.length === 0) {
+    throw new SourceError({
+      kind: 'empty',
+      adapterId: id,
+      seriesRef,
+      detail: 'every row was missing a usable date or value',
+    })
+  }
+  points.sort((a, b) => (a.t < b.t ? -1 : a.t > b.t ? 1 : 0))
+  return { name: params.filter ? `${seriesRef} (${params.filter})` : seriesRef, points }
+}
+
+/**
+ * Fetch and normalize one fiscaldata series.
+ *
+ * @param {{ seriesRef: string, params?: { filter?: string, valueField?: string }, range?: 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, params } = req
+  const url = buildUrl(seriesRef, { filter: params?.filter })
+  const { status, body } = await getText({
+    fetch: deps.fetch,
+    url,
+    adapterId: id,
+    seriesRef,
+    signal: deps.signal,
+    allowHttpError: true,
+  })
+  if (status >= 400 && status < 500) {
+    // fiscaldata answers an unknown dataset with an HTML 404 page.
+    throw new SourceError({
+      kind: 'unsupported',
+      adapterId: id,
+      seriesRef,
+      detail: `fiscaldata returned HTTP ${status} for dataset ${seriesRef}`,
+      httpStatus: status,
+    })
+  }
+  if (status >= 500) {
+    throw new SourceError({
+      kind: 'http',
+      adapterId: id,
+      seriesRef,
+      detail: `fiscaldata is unavailable (HTTP ${status})`,
+      httpStatus: status,
+    })
+  }
+  const { name, points } = parseDataset(body, seriesRef, params ?? {})
+  return {
+    adapterId: id,
+    seriesRef,
+    points,
+    meta: { name, unit: '%', freq: 'monthly' },
+    fetchedAt: deps.clock.now().toISOString(),
+    sourceRef: sourceRef(seriesRef, params),
+    raw: { url, httpStatus: status, rows: payloadRowCount(body) },
+  }
+}
+
+/**
+ * Row count of a payload, tolerant of a malformed body (used for 'raw' only).
+ *
+ * @param {string} body - response body.
+ * @returns {number} row count or 0.
+ */
+function payloadRowCount(body) {
+  try {
+    return JSON.parse(body)?.data?.length ?? 0
+  } catch {
+    return 0
+  }
+}

package/src/sources/worldbank.js

@@ -0,0 +1,170 @@
+/**
+ * World Bank adapter (docs/04 §5).
+ *
+ * The response is a **two-element array** '[meta, rows]', and 'rows' is 'null'
+ * (not '[]') when the query has no data. Annual values carry only a year, which
+ * is normalized to December 31 of that year — inventing '-01-01' would claim a
+ * precision the source does not have.
+ *
+ * @module sources/worldbank
+ */
+import { SourceError } from '../core/types.js'
+import { parseNumber } from '../core/stats/series.js'
+import { getText, parseJson } from './http.js'
+
+/** @type {string} */
+export const id = 'worldbank'
+
+/** @type {string} */
+export const label = 'World Bank'
+
+/**
+ * The World Bank answers in 0.4–14s from this network, well past the default 6s
+ * per-source budget, so it declares its own (see 'sources/registry.sourceTimeoutMs').
+ */
+export const timeoutMs = 15_000
+
+/** @type {Array<{ kinds: string[], frequencies: string[] }>} */
+export const capabilities = [{ kinds: ['macro'], frequencies: ['annual'] }]
+
+/** How far back the adapter asks for, so a 5-year window always has history. */
+const DEFAULT_START_YEAR = '2000'
+
+/**
+ * Open-ended end of the requested span. '3000' keeps the query deterministic
+ * (no clock read) while still meaning "everything published".
+ */
+const OPEN_END_YEAR = '3000'
+
+/**
+ * Build an indicator URL.
+ *
+ * @param {string} seriesRef - indicator id, e.g. 'NY.GDP.MKTP.CD'.
+ * @param {{ country?: string, date?: string, perPage?: number }} [params] - catalog params.
+ * @returns {string} request URL.
+ */
+export function buildUrl(seriesRef, { country = 'US', date = `${DEFAULT_START_YEAR}:${OPEN_END_YEAR}`, perPage = 100 } = {}) {
+  return (
+    `https://api.worldbank.org/v2/country/${encodeURIComponent(country)}` +
+    `/indicator/${encodeURIComponent(seriesRef)}` +
+    `?format=json&per_page=${perPage}&date=${date}`
+  )
+}
+
+/**
+ * Indicator landing page plus the API URL.
+ *
+ * @param {string} seriesRef - indicator id.
+ * @param {{ country?: string }} [params] - catalog params.
+ * @returns {{ adapterId: string, url: string, apiUrl: string, seriesRef: string, label: string }} source reference.
+ */
+export function sourceRef(seriesRef, params = {}) {
+  const country = params.country ?? 'US'
+  return {
+    adapterId: id,
+    url: `https://data.worldbank.org/indicator/${encodeURIComponent(seriesRef)}?locations=${encodeURIComponent(country)}`,
+    apiUrl: buildUrl(seriesRef, { country }),
+    seriesRef: `${seriesRef}@${country}`,
+    label,
+  }
+}
+
+/**
+ * Parse a World Bank payload.
+ *
+ * @param {string} body - response body.
+ * @param {string} seriesRef - indicator id (for errors).
+ * @returns {{ name: string, points: Array<{ t: string, v: number }> }} parsed series.
+ */
+export function parseIndicator(body, seriesRef) {
+  const payload = parseJson(body, id, seriesRef)
+  if (!Array.isArray(payload)) {
+    throw new SourceError({ kind: 'parse', adapterId: id, seriesRef, detail: 'response is not the [meta, rows] pair' })
+  }
+  const rows = payload[1]
+  if (rows === null || rows === undefined) {
+    // The documented "no data" shape: `[ {message: [...]}, null ]`
+    const message = payload[0]?.message?.[0]?.value
+    throw new SourceError({
+      kind: 'empty',
+      adapterId: id,
+      seriesRef,
+      detail: `World Bank returned no rows for this query${message ? ` (${message})` : ''}`,
+    })
+  }
+  if (!Array.isArray(rows)) {
+    throw new SourceError({ kind: 'parse', adapterId: id, seriesRef, detail: 'the rows element is not an array' })
+  }
+  if (rows.length === 0) {
+    throw new SourceError({ kind: 'empty', adapterId: id, seriesRef, detail: 'the rows array is empty' })
+  }
+  const points = []
+  let name = seriesRef
+  for (const row of rows) {
+    if (row === null || typeof row !== 'object') continue
+    if (row.indicator?.value) name = row.indicator.value
+    const year = Number(row.date)
+    const value = parseNumber(row.value)
+    if (!Number.isInteger(year) || value === undefined) continue
+    // Annual observation: date it at the end of its year.
+    points.push({ t: `${String(year).padStart(4, '0')}-12-31`, v: value })
+  }
+  if (points.length === 0) {
+    throw new SourceError({
+      kind: 'empty',
+      adapterId: id,
+      seriesRef,
+      detail: 'every row had a null year or value',
+    })
+  }
+  points.sort((a, b) => (a.t < b.t ? -1 : a.t > b.t ? 1 : 0))
+  return { name, points }
+}
+
+/**
+ * Fetch and normalize one indicator.
+ *
+ * @param {{ seriesRef: string, params?: { country?: string, date?: string } }} 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 { status, body } = await getText({
+    fetch: deps.fetch,
+    url,
+    adapterId: id,
+    seriesRef,
+    signal: deps.signal,
+    allowHttpError: true,
+  })
+  if (status >= 400 && status < 500) {
+    throw new SourceError({
+      kind: 'unsupported',
+      adapterId: id,
+      seriesRef,
+      detail: `World Bank returned HTTP ${status} for ${seriesRef}; the indicator or country is not valid`,
+      httpStatus: status,
+    })
+  }
+  if (status >= 500) {
+    throw new SourceError({
+      kind: 'http',
+      adapterId: id,
+      seriesRef,
+      detail: `World Bank is unavailable (HTTP ${status})`,
+      httpStatus: status,
+    })
+  }
+  const { name, points } = parseIndicator(body, seriesRef)
+  return {
+    adapterId: id,
+    seriesRef,
+    points,
+    meta: { name, unit: undefined, freq: 'annual' },
+    fetchedAt: deps.clock.now().toISOString(),
+    sourceRef: sourceRef(seriesRef, params),
+    raw: { url, httpStatus: status, rows: points.length },
+  }
+}