dsh-simple-usage-info 0.1.0

package/lib/holiday-source.js

@@ -0,0 +1,154 @@
+/**
+ * Chinese public holiday source.
+ *
+ * DeepSeek's peak window excludes Chinese public holidays, and the statutory
+ * arrangement is republished every November and is not derivable — the observed
+ * days move with the lunar calendar and the annual 调休 adjustments. So instead
+ * of maintaining a table by hand, this fetches one that is already maintained:
+ *
+ *   https://github.com/NateScarlet/holiday-cn
+ *
+ * That repository scrapes the State Council announcements daily in CI and
+ * publishes one JSON file per year:
+ *
+ *   { "year": 2026, "papers": ["https://www.gov.cn/..."],
+ *     "days": [ { "name": "元旦", "date": "2026-01-01", "isOffDay": true }, ... ] }
+ *
+ * `isOffDay: true` is a statutory day off; `isOffDay: false` is a 调休 makeup
+ * workday. `lib/holidays.js` stays as an offline fallback for when the fetch
+ * fails. The fetcher is injected so it can be exercised without a network.
+ *
+ * @module dsh-simple-usage-info/holiday-source
+ */
+
+/** Where the maintained data lives; `{year}` is substituted. */
+export const DEFAULT_HOLIDAY_URL = 'https://raw.githubusercontent.com/NateScarlet/holiday-cn/master/{year}.json'
+
+/** How long one successful snapshot stays fresh. */
+export const DEFAULT_TTL_MS = 12 * 60 * 60 * 1000
+
+/** Remote request timeout. */
+export const DEFAULT_TIMEOUT_MS = 10000
+
+/** Sorted, de-duplicated union. */
+function union(lists) {
+  return [...new Set(lists.flat())].sort()
+}
+
+/**
+ * Read one year's document.
+ * @param options - the injected fetch, template, timeout, and clock.
+ * @param year - the calendar year to read.
+ * @returns the year's days, or `undefined` when the notice is not published yet.
+ * @throws Error when the request fails or the body is unusable.
+ */
+async function loadYear(options, year) {
+  const url = options.urlTemplate.replace('{year}', String(year))
+  const response = await options.fetchImpl(url, {
+    headers: { accept: 'application/json' },
+    signal: AbortSignal.timeout(options.timeoutMs)
+  })
+  if (response.ok !== true) throw new Error(`${url} answered HTTP ${response.status}`)
+  const body = await response.json()
+  const days = Array.isArray(body?.days) ? body.days : []
+  // holiday-cn publishes an empty placeholder before the State Council notice
+  // lands, and an empty `days` means "not announced", never "no holidays".
+  if (days.length === 0) return undefined
+  return {
+    year: Number(body.year ?? year),
+    holidays: days.filter((day) => day.isOffDay === true).map((day) => String(day.date)),
+    makeupWorkdays: days.filter((day) => day.isOffDay !== true).map((day) => String(day.date)),
+    papers: Array.isArray(body.papers) ? body.papers.map(String) : []
+  }
+}
+
+/**
+ * Build a lazily-refreshed holiday source.
+ *
+ * `refresh()` never rejects: a failed year is recorded and the previous snapshot
+ * is kept, so the caller can always render something.
+ * @param options - configuration and injectable seams.
+ * @returns the source handle.
+ */
+export function createHolidaySource(options) {
+  const settings = {
+    urlTemplate: options?.urlTemplate ?? DEFAULT_HOLIDAY_URL,
+    ttlMs: options?.ttlMs ?? DEFAULT_TTL_MS,
+    timeoutMs: options?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    fetchImpl: options?.fetchImpl ?? globalThis.fetch,
+    now: options?.now ?? Date.now,
+    log: options?.log ?? (() => {})
+  }
+
+  /** The last successful snapshot, if any. */
+  let snapshot
+  /** The in-flight refresh, so concurrent callers share one round trip. */
+  let inflight = null
+  /** When the last refresh finished, successful or not. */
+  let attemptedAt = 0
+
+  /** Whether a remote source is configured at all. */
+  const enabled = () => settings.urlTemplate !== '' && typeof settings.fetchImpl === 'function'
+
+  /**
+   * Whether a refresh is worth starting for these years.
+   * @param years - the years the caller needs covered.
+   * @returns true when the snapshot is missing, stale, or short of a year.
+   */
+  function stale(years) {
+    if (!enabled()) return false
+    if (snapshot === undefined) return true
+    if (settings.now() - attemptedAt > settings.ttlMs) return true
+    return years.some((year) => !snapshot.years.includes(year))
+  }
+
+  /**
+   * Fetch every requested year and publish one merged snapshot. A disabled
+   * source resolves to the current snapshot without touching the network, so a
+   * caller that forgets to check {@link stale} still cannot fetch.
+   * @param years - the years to cover.
+   * @returns the snapshot after the attempt (unchanged when every year failed).
+   */
+  function refresh(years) {
+    if (!enabled()) return Promise.resolve(snapshot)
+    if (inflight !== null) return inflight
+    inflight = (async () => {
+      const loaded = []
+      const failures = []
+      for (const year of years) {
+        try {
+          const one = await loadYear(settings, year)
+          if (one !== undefined) loaded.push(one)
+        } catch (error) {
+          failures.push(`${year}: ${String(error?.message ?? error)}`)
+        }
+      }
+      attemptedAt = settings.now()
+      if (loaded.length > 0) {
+        snapshot = {
+          holidays: union(loaded.map((one) => one.holidays)),
+          makeupWorkdays: union(loaded.map((one) => one.makeupWorkdays)),
+          years: [...new Set(loaded.map((one) => one.year))].sort((left, right) => left - right),
+          papers: union(loaded.map((one) => one.papers)),
+          fetchedAt: settings.now()
+        }
+      }
+      if (failures.length > 0) {
+        settings.log(
+          `usage-info: holiday refresh incomplete (${failures.join('; ')})` +
+            (snapshot === undefined ? '; falling back to the bundled table' : '; keeping the last snapshot')
+        )
+      }
+      inflight = null
+      return snapshot
+    })()
+    return inflight
+  }
+
+  return {
+    /** The current snapshot, or undefined before the first success. */
+    peek: () => snapshot,
+    stale,
+    refresh
+  }
+}

package/lib/holidays.d.ts

@@ -0,0 +1,19 @@
+/**
+ * dsh-simple-usage-info — bundled Chinese public holiday table types.
+ * @module dsh-simple-usage-info/holidays
+ */
+
+/** Every calendar year the bundled table covers. */
+export declare const COVERED_YEARS: readonly number[]
+
+/** Every announced public holiday date across the covered years, sorted. */
+export declare function bundledHolidays(): string[]
+
+/** Every announced 调休 makeup workday across the covered years, sorted. */
+export declare function bundledMakeupWorkdays(): string[]
+
+/**
+ * The State Council citation for one year's arrangement.
+ * @returns the notice reference, or undefined when the year is not covered.
+ */
+export declare function noticeFor(year: number): string | undefined

package/lib/holidays.js

@@ -0,0 +1,109 @@
+/**
+ * Chinese public holidays — the offline fallback table.
+ *
+ * The primary source is fetched at runtime from a list that is already
+ * maintained (`lib/holiday-source.js` → NateScarlet/holiday-cn). This table is
+ * what the plugin uses when that fetch has never succeeded, so an offline host
+ * still prices holidays correctly instead of silently treating them as ordinary
+ * weekdays.
+ *
+ * The dates are Chinese calendar days; because every peak window (01:00–10:00
+ * UTC) sits inside one Chinese day (09:00–18:00 CST), looking them up by UTC
+ * date is equivalent.
+ *
+ * The 2026 entry below is the State Council announcement (Guo Ban Fa Ming Dian
+ * [2025] No. 7), verified date-for-date against holiday-cn's 2026.json: 33 days
+ * off and 6 makeup workdays, identical.
+ *
+ * Being a fallback rather than the source of truth, it needs no annual
+ * maintenance — a year it does not cover simply reports itself as uncovered when
+ * the fetch is also unavailable.
+ *
+ * @module dsh-simple-usage-info/holidays
+ */
+
+/**
+ * One year's announced arrangement.
+ * `ranges` are inclusive `YYYY-MM-DD` spans of days off; `makeupWorkdays` are
+ * weekend days the notice designates as working days.
+ */
+const NOTICES = {
+  2026: {
+    notice: 'Guo Ban Fa Ming Dian [2025] No. 7 (4 November 2025)',
+    ranges: [
+      // New Year's Day, 3 days.
+      ['2026-01-01', '2026-01-03'],
+      // Spring Festival, 9 days.
+      ['2026-02-15', '2026-02-23'],
+      // Qingming Festival, 3 days.
+      ['2026-04-04', '2026-04-06'],
+      // Labor Day, 5 days.
+      ['2026-05-01', '2026-05-05'],
+      // Dragon Boat Festival, 3 days.
+      ['2026-06-19', '2026-06-21'],
+      // Mid-Autumn Festival, 3 days.
+      ['2026-09-25', '2026-09-27'],
+      // National Day, 7 days.
+      ['2026-10-01', '2026-10-07']
+    ],
+    makeupWorkdays: [
+      '2026-01-04', // Sunday, for New Year's Day
+      '2026-02-14', // Saturday, for Spring Festival
+      '2026-02-28', // Saturday, for Spring Festival
+      '2026-05-09', // Saturday, for Labor Day
+      '2026-09-20', // Sunday, for National Day
+      '2026-10-10' // Saturday, for National Day
+    ]
+  }
+}
+
+/** Every calendar year this table covers. */
+export const COVERED_YEARS = Object.keys(NOTICES).map(Number).sort()
+
+/** `YYYY-MM-DD` for a UTC date. */
+function dayKey(year, month, day) {
+  const pad = (value) => String(value).padStart(2, '0')
+  return `${year}-${pad(month + 1)}-${pad(day)}`
+}
+
+/**
+ * Expand one inclusive `YYYY-MM-DD`..`YYYY-MM-DD` span.
+ * @param from - first day off.
+ * @param to - last day off.
+ * @returns every date in the span.
+ */
+function expandRange(from, to) {
+  const start = Date.parse(`${from}T00:00:00Z`)
+  const end = Date.parse(`${to}T00:00:00Z`)
+  const dates = []
+  for (let at = start; at <= end; at += 86400000) {
+    const date = new Date(at)
+    dates.push(dayKey(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()))
+  }
+  return dates
+}
+
+/**
+ * Every announced public holiday date across the covered years.
+ * @returns a sorted list of `YYYY-MM-DD`.
+ */
+export function bundledHolidays() {
+  return COVERED_YEARS.flatMap((year) => NOTICES[year].ranges.flatMap(([from, to]) => expandRange(from, to))).sort()
+}
+
+/**
+ * Every announced makeup workday across the covered years.
+ * @returns a sorted list of `YYYY-MM-DD`.
+ */
+export function bundledMakeupWorkdays() {
+  return COVERED_YEARS.flatMap((year) => [...NOTICES[year].makeupWorkdays]).sort()
+}
+
+/**
+ * The citation for one year's arrangement.
+ * @param year - calendar year.
+ * @returns the notice reference, or undefined when uncovered.
+ */
+export function noticeFor(year) {
+  return NOTICES[year]?.notice
+}

package/lib/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * dsh-simple-usage-info — host (Node) half type surface.
+ * @module dsh-simple-usage-info
+ */
+import type { Context } from '@deepseek-ai/cordis'
+
+/** Cordis plugin name. */
+export declare const name = 'dsh-simple-usage-info'
+/** Host services required before the balance route can register. */
+export declare const inject: string[]
+/** The one route path this plugin owns, shared with the browser half. */
+export declare const BALANCE_PATH = '/usage/balance'
+/** Plugin configuration schema. */
+export declare const Config: unknown
+
+/** One currency's balance, exactly as the DeepSeek API reports it. */
+export interface DeepSeekBalanceInfo {
+  readonly currency: 'CNY' | 'USD'
+  readonly total_balance: string
+  readonly granted_balance: string
+  readonly topped_up_balance: string
+}
+
+/** The DeepSeek `GET /user/balance` document. */
+export interface DeepSeekBalance {
+  readonly is_available: boolean
+  readonly balance_infos: readonly DeepSeekBalanceInfo[]
+}
+
+/** What `GET /usage/balance` answers. Both branches carry the pricing block. */
+export type BalancePayload =
+  | {
+      readonly ok: true
+      readonly balance: DeepSeekBalance
+      readonly pricing: import('./pricing.js').PricingReading
+      readonly fetchedAt: number
+    }
+  | {
+      readonly ok: false
+      readonly error: { readonly code: string; readonly message: string }
+      readonly pricing: import('./pricing.js').PricingReading
+      readonly fetchedAt: number
+    }
+
+/** Host plugin body: one cached, read-only balance route. */
+export declare function apply(ctx: Context, config: unknown): void

package/lib/index.js

@@ -0,0 +1,263 @@
+/**
+ * dsh-simple-usage-info — host (Node) half.
+ *
+ * Registers one exact read-only HTTP route on the Web GUI's server. The route
+ * resolves the same credential the shipped `deepseek-official` model route uses
+ * (`DEEPSEEK_API_KEY`, through the credentials service) and asks the public
+ * DeepSeek balance API for the account balance, then answers the browser half
+ * with plain JSON. The key never leaves this process.
+ *
+ * Route: GET /usage/balance
+ *   200 { ok: true,  balance: { is_available, balance_infos: [...] }, pricing, fetchedAt }
+ *   200 { ok: false, error: { code, message }, pricing, fetchedAt }
+ *   403 when the request's Host header is not a loopback host
+ *   405 for any other method.
+ *
+ * `pricing` is computed fresh on every request from the server clock; only the
+ * upstream balance call is cached.
+ *
+ * The route is registered directly on the WebServer, so it sits outside the
+ * Web GUI's `/api` authentication fence. It answers loopback hosts only (and
+ * anything when the operator deliberately binds `0.0.0.0`), which blocks a
+ * malicious page from reading the balance through DNS rebinding, and it never
+ * returns key material — only the numbers the DeepSeek API reports.
+ *
+ * The route is deliberately cache-backed: the browser half polls it, and
+ * `refreshMs` bounds how often the upstream API is actually called.
+ *
+ * @module dsh-simple-usage-info
+ */
+import z from '@deepseek-ai/schemastery'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment'
+import { normalizeSchedule, readPricing, withHolidayData } from './pricing.js'
+import { createHolidaySource, DEFAULT_HOLIDAY_URL } from './holiday-source.js'
+
+/** Cordis plugin name. */
+export const name = 'dsh-simple-usage-info'
+
+/** The WebServer must exist before the balance route can register. */
+export const inject = ['webServer']
+
+/**
+ * The one route path this plugin owns. The browser half hard-codes the same
+ * constant, so it is exported rather than configurable.
+ */
+export const BALANCE_PATH = '/usage/balance'
+
+/** Plugin configuration, validated by Schemastery. */
+export const Config = z.object({
+  /** DeepSeek API origin; the balance endpoint lives at its root. */
+  baseURL: z.string().default('https://api.deepseek.com'),
+  /** Credential-reference name holding the API key. */
+  apiKeyEnv: z.string().role('credential-ref').default('DEEPSEEK_API_KEY'),
+  /** How long one upstream balance answer stays fresh. */
+  refreshMs: z.number().default(60000),
+  /** Upstream request timeout. */
+  timeoutMs: z.number().default(15000),
+  /** Peak-rate windows as `HH:MM-HH:MM` UTC; everything else is off-peak. */
+  peakWindows: z.array(z.string()).default(['01:00-04:00', '06:00-10:00']),
+  /** Peak weekdays, 0 = Sunday through 6 = Saturday. */
+  peakDays: z.array(z.number()).default([1, 2, 3, 4, 5]),
+  /** Extra `YYYY-MM-DD` UTC dates priced off-peak in full, on top of the fetched holidays. */
+  holidays: z.array(z.string()).default([]),
+  /** Extra `YYYY-MM-DD` UTC makeup workdays; only meaningful with `makeupWorkdaysArePeak`. */
+  makeupWorkdays: z.array(z.string()).default([]),
+  /**
+   * Treat 调休 makeup workdays as peak days. The published rule says "Monday
+   * through Friday", which makes them off-peak, so this defaults off.
+   */
+  makeupWorkdaysArePeak: z.boolean().default(false),
+  /**
+   * Where to read the maintained Chinese holiday data; `{year}` is substituted.
+   * Leave the URL empty to stay offline and use the bundled table.
+   */
+  holidayURL: z.string().default(DEFAULT_HOLIDAY_URL),
+  /** How long one fetched holiday snapshot stays fresh. */
+  holidayRefreshMs: z.number().default(43200000),
+  /** Merge the bundled State Council holiday table as a fallback; false leaves only `holidays`. */
+  useBundledHolidays: z.boolean().default(true),
+  /** Off-peak discount, as a percentage of the peak rate. */
+  offPeakDiscountPercent: z.number().default(50)
+})
+
+/** A forced refresh may never hit the network more often than this. */
+const MIN_REFRESH_MS = 5000
+
+/** Hostnames that can only mean the local machine. */
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '[::1]'])
+
+/**
+ * Whether a request's `Host` header is one this route answers.
+ *
+ * The route lives outside the GUI's `/api` auth fence, so without this check a
+ * malicious page could use DNS rebinding to read the balance from
+ * `http://127.0.0.1:<port>/usage/balance`. A deliberate `0.0.0.0` bind is the
+ * operator's stated intent to expose the server, so that posture answers any
+ * host.
+ * @param hostHeader - the raw `Host` header.
+ * @param bindHost - the WebServer's configured bind host.
+ * @returns true when the request may be answered.
+ */
+function hostAllowed(hostHeader, bindHost) {
+  if (bindHost === '0.0.0.0') return true
+  if (typeof hostHeader !== 'string' || hostHeader === '') return false
+  const closing = hostHeader.startsWith('[') ? hostHeader.indexOf(']') : -1
+  const hostname = closing >= 0 ? hostHeader.slice(0, closing + 1) : hostHeader.split(':', 1)[0]
+  return LOOPBACK_HOSTS.has(hostname.toLowerCase())
+}
+
+/** Write one JSON response. `no-store` keeps browsers from caching a balance. */
+function sendJson(res, status, body) {
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.setHeader('cache-control', 'no-store')
+  res.end(JSON.stringify(body))
+}
+
+/** An error carrying a stable machine-readable code for the browser half. */
+function taggedError(code, message) {
+  const error = new Error(message)
+  error.code = code
+  return error
+}
+
+/**
+ * Resolve the API key exactly the way `@deepseek-ai/dsh-llm-deepseek-api-key`
+ * does: the credentials seam first (which itself layers the launch environment),
+ * then the raw launch environment when no seam is mounted.
+ * @param ctx - host plugin context.
+ * @param config - validated plugin configuration.
+ * @returns the secret key value.
+ */
+async function resolveApiKey(ctx, config) {
+  const ref = credentialRef(config.apiKeyEnv)
+  const credentials = ctx.get('credentials')
+  if (credentials !== undefined) {
+    const hit = await credentials.resolve(ref)
+    if (hit !== undefined && hit.value.length > 0) return hit.value
+  }
+  const ambient = launchEnvironmentOf(ctx).get(ref)
+  if (ambient !== undefined && ambient.value.length > 0) return ambient.value
+  throw taggedError(
+    'missing-credential',
+    `no API key behind ${String(ref)}; store it through the credentials service or export it before launching dsh`
+  )
+}
+
+/**
+ * Read the account balance from the public DeepSeek API.
+ * @param ctx - host plugin context.
+ * @param config - validated plugin configuration.
+ * @returns the parsed balance document.
+ */
+async function fetchBalance(ctx, config) {
+  const key = await resolveApiKey(ctx, config)
+  const url = `${config.baseURL.replace(/\/+$/, '')}/user/balance`
+  const response = await fetch(url, {
+    method: 'GET',
+    headers: { authorization: `Bearer ${key}`, accept: 'application/json' },
+    signal: AbortSignal.timeout(config.timeoutMs)
+  })
+  if (!response.ok) {
+    const detail = await response.text().catch(() => '')
+    const code = response.status === 401 || response.status === 403 ? 'invalid-credential' : 'upstream-error'
+    throw taggedError(code, `DeepSeek answered HTTP ${response.status}${detail === '' ? '' : ` — ${detail.slice(0, 200)}`}`)
+  }
+  return await response.json()
+}
+
+/**
+ * Host plugin body: one cached, read-only balance route.
+ * @param ctx - host plugin context.
+ * @param config - validated plugin configuration.
+ */
+export function apply(ctx, config) {
+  // A malformed schedule is a configuration error, so fail here rather than
+  // answering every request with a broken pricing block.
+  const schedule = normalizeSchedule(config)
+  /** The maintained holiday data, refreshed in the background. */
+  const holidays = createHolidaySource({
+    urlTemplate: config.holidayURL,
+    ttlMs: config.holidayRefreshMs,
+    timeoutMs: config.timeoutMs,
+    log: (message) => ctx.logger?.warn?.(message)
+  })
+  /**
+   * The calendar years a reading can land in. holiday-cn files a date under the
+   * year of the State Council paper rather than the date, so December can depend
+   * on the next year's document and both must be present.
+   */
+  const neededYears = () => {
+    const year = new Date().getUTCFullYear()
+    return [year, year + 1]
+  }
+  // Warm the cache at load time; a failure just leaves the bundled table in use.
+  if (holidays.stale(neededYears())) void holidays.refresh(neededYears())
+
+  /** Cache: last good payload, its timestamp, and the in-flight read. */
+  const cache = { payload: undefined, at: 0, inflight: undefined }
+  const ttl = Math.max(MIN_REFRESH_MS, config.refreshMs)
+
+  /**
+   * Answer from cache, or re-read upstream. Concurrent callers share one read,
+   * and a failed read never replaces the last good payload.
+   * @param force - bypass the freshness window (still floored by MIN_REFRESH_MS).
+   * @returns the payload the route serializes.
+   */
+  const read = async (force) => {
+    const age = Date.now() - cache.at
+    if (cache.payload !== undefined && age < (force ? MIN_REFRESH_MS : ttl)) return cache.payload
+    if (cache.inflight !== undefined) return cache.inflight
+    cache.inflight = (async () => {
+      try {
+        const balance = await fetchBalance(ctx, config)
+        cache.payload = { ok: true, balance, fetchedAt: Date.now() }
+        cache.at = Date.now()
+        return cache.payload
+      } catch (error) {
+        const code = typeof error?.code === 'string' ? error.code : 'request-failed'
+        const message = String(error?.message ?? error)
+        ctx.logger?.warn?.('usage-info: balance read failed (%s): %s', code, message)
+        return { ok: false, error: { code, message }, fetchedAt: Date.now() }
+      } finally {
+        cache.inflight = undefined
+      }
+    })()
+    return cache.inflight
+  }
+
+  const route = {
+    kind: 'exact',
+    path: BALANCE_PATH,
+    handler: async (req, res) => {
+      if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.setHeader('allow', 'GET, HEAD')
+        sendJson(res, 405, { ok: false, error: { code: 'method-not-allowed', message: 'use GET' } })
+        return
+      }
+      if (!hostAllowed(req.headers?.host, ctx.webServer?.host ?? '127.0.0.1')) {
+        sendJson(res, 403, { ok: false, error: { code: 'forbidden-host', message: 'this route answers loopback hosts only' } })
+        return
+      }
+      const force = new URL(req.url ?? '/', 'http://localhost').searchParams.get('refresh') === '1'
+      const payload = await read(force)
+      // Keep the holiday calendar warm without ever blocking a request on it: a
+      // stale snapshot is refreshed in the background, and this request answers
+      // from whatever is already cached (fetched data, else the bundled table).
+      const years = neededYears()
+      if (holidays.stale(years)) void holidays.refresh(years)
+      // The pricing window is arithmetic on the server clock, so it is read
+      // fresh here rather than cached with the upstream balance.
+      const body = { ...payload, pricing: readPricing(withHolidayData(schedule, holidays.peek()), Date.now()) }
+      if (req.method === 'HEAD') {
+        res.statusCode = 200
+        res.end()
+        return
+      }
+      sendJson(res, 200, body)
+    }
+  }
+
+  ctx.effect(() => ctx.webServer.register(route), `usage-info: ${BALANCE_PATH}`)
+}