@linxin666/dsh-usage 0.4.4 → 0.4.5

package/src/core/holidays.ts

@@ -0,0 +1,248 @@
+/**
+ * Chinese public-holiday dates, Beijing calendar days, as `YYYY-MM-DD`.
+ *
+ * The DeepSeek peak rule bills a public holiday off-peak in full, and the
+ * State Council publishes these dates per year, so they cannot be derived
+ * from a rule. This module is that data; `pricing.ts` keeps the arithmetic.
+ *
+ * Adjusted workdays are deliberately absent: the provider counts the
+ * calendar day, so an adjusted Saturday or Sunday is off-peak exactly like
+ * any other weekend and listing it would price it as peak.
+ *
+ * Source: the yearly schedules in bastengao/chinese-holidays-node
+ * (`data/<year>.json`, MIT). Only the `holiday` entries are taken; that
+ * package's runtime code (which fetches over the network) and its
+ * dependencies are not vendored.
+ *
+ * Coverage ends at the newest year below. A year with no entry is priced as
+ * if it had no holidays, which is the documented default of
+ * {@link PublicHolidayCalendar} in `pricing.ts`.
+ * @module @linxin666/dsh-usage/core/holidays
+ */
+
+/** Public-holiday dates keyed by Beijing calendar year. */
+export const CHINESE_PUBLIC_HOLIDAYS: Readonly<Record<string, readonly string[]>> = {
+  "2020": [
+    "2020-01-24",
+    "2020-01-25",
+    "2020-01-26",
+    "2020-01-27",
+    "2020-01-28",
+    "2020-01-29",
+    "2020-01-30",
+    "2020-04-04",
+    "2020-04-05",
+    "2020-04-06",
+    "2020-05-01",
+    "2020-05-02",
+    "2020-05-03",
+    "2020-05-04",
+    "2020-05-05",
+    "2020-06-25",
+    "2020-06-26",
+    "2020-06-27",
+    "2020-10-01",
+    "2020-10-02",
+    "2020-10-03",
+    "2020-10-04",
+    "2020-10-05",
+    "2020-10-06",
+    "2020-10-07",
+    "2020-10-08"
+  ],
+  "2021": [
+    "2021-01-01",
+    "2021-01-02",
+    "2021-01-03",
+    "2021-02-11",
+    "2021-02-12",
+    "2021-02-13",
+    "2021-02-14",
+    "2021-02-15",
+    "2021-02-16",
+    "2021-02-17",
+    "2021-04-03",
+    "2021-04-04",
+    "2021-04-05",
+    "2021-05-01",
+    "2021-05-02",
+    "2021-05-03",
+    "2021-05-04",
+    "2021-05-05",
+    "2021-06-12",
+    "2021-06-13",
+    "2021-06-14",
+    "2021-09-19",
+    "2021-09-20",
+    "2021-09-21",
+    "2021-10-01",
+    "2021-10-02",
+    "2021-10-03",
+    "2021-10-04",
+    "2021-10-05",
+    "2021-10-06",
+    "2021-10-07"
+  ],
+  "2022": [
+    "2022-01-01",
+    "2022-01-02",
+    "2022-01-03",
+    "2022-01-31",
+    "2022-02-01",
+    "2022-02-02",
+    "2022-02-03",
+    "2022-02-04",
+    "2022-02-05",
+    "2022-02-06",
+    "2022-04-03",
+    "2022-04-04",
+    "2022-04-05",
+    "2022-04-30",
+    "2022-05-01",
+    "2022-05-02",
+    "2022-05-03",
+    "2022-05-04",
+    "2022-06-03",
+    "2022-06-04",
+    "2022-06-05",
+    "2022-09-10",
+    "2022-09-11",
+    "2022-09-12",
+    "2022-10-01",
+    "2022-10-02",
+    "2022-10-03",
+    "2022-10-04",
+    "2022-10-05",
+    "2022-10-06",
+    "2022-10-07"
+  ],
+  "2023": [
+    "2022-12-31",
+    "2023-01-01",
+    "2023-01-02",
+    "2023-01-21",
+    "2023-01-22",
+    "2023-01-23",
+    "2023-01-24",
+    "2023-01-25",
+    "2023-01-26",
+    "2023-01-27",
+    "2023-04-29",
+    "2023-04-30",
+    "2023-05-01",
+    "2023-05-02",
+    "2023-05-03",
+    "2023-06-22",
+    "2023-06-23",
+    "2023-06-24",
+    "2023-09-29",
+    "2023-09-30",
+    "2023-10-01",
+    "2023-10-02",
+    "2023-10-03",
+    "2023-10-04",
+    "2023-10-05",
+    "2023-10-06"
+  ],
+  "2024": [
+    "2023-12-30",
+    "2023-12-31",
+    "2024-01-01",
+    "2024-02-10",
+    "2024-02-11",
+    "2024-02-12",
+    "2024-02-13",
+    "2024-02-14",
+    "2024-02-15",
+    "2024-02-16",
+    "2024-02-17",
+    "2024-04-04",
+    "2024-04-05",
+    "2024-04-06",
+    "2024-05-01",
+    "2024-05-02",
+    "2024-05-03",
+    "2024-05-04",
+    "2024-05-05",
+    "2024-06-08",
+    "2024-06-09",
+    "2024-06-10",
+    "2024-09-15",
+    "2024-09-16",
+    "2024-09-17",
+    "2024-10-01",
+    "2024-10-02",
+    "2024-10-03",
+    "2024-10-04",
+    "2024-10-05",
+    "2024-10-06",
+    "2024-10-07"
+  ],
+  "2025": [
+    "2025-01-28",
+    "2025-01-29",
+    "2025-01-30",
+    "2025-01-31",
+    "2025-02-01",
+    "2025-02-02",
+    "2025-02-03",
+    "2025-02-04",
+    "2025-04-04",
+    "2025-04-05",
+    "2025-04-06",
+    "2025-05-01",
+    "2025-05-02",
+    "2025-05-03",
+    "2025-05-04",
+    "2025-05-05",
+    "2025-05-31",
+    "2025-06-01",
+    "2025-06-02",
+    "2025-10-01",
+    "2025-10-02",
+    "2025-10-03",
+    "2025-10-04",
+    "2025-10-05",
+    "2025-10-06",
+    "2025-10-07",
+    "2025-10-08"
+  ],
+  "2026": [
+    "2026-01-01",
+    "2026-01-02",
+    "2026-01-03",
+    "2026-02-15",
+    "2026-02-16",
+    "2026-02-17",
+    "2026-02-18",
+    "2026-02-19",
+    "2026-02-20",
+    "2026-02-21",
+    "2026-02-22",
+    "2026-02-23",
+    "2026-04-04",
+    "2026-04-05",
+    "2026-04-06",
+    "2026-05-01",
+    "2026-05-02",
+    "2026-05-03",
+    "2026-05-04",
+    "2026-05-05",
+    "2026-06-19",
+    "2026-06-20",
+    "2026-06-21",
+    "2026-09-25",
+    "2026-09-26",
+    "2026-09-27",
+    "2026-10-01",
+    "2026-10-02",
+    "2026-10-03",
+    "2026-10-04",
+    "2026-10-05",
+    "2026-10-06",
+    "2026-10-07"
+  ]
+}
+
+/** The newest year this table covers; later years carry no entry. */
+export const HOLIDAY_TABLE_LAST_YEAR = 2026

package/src/core/ledger.ts

@@ -15,6 +15,19 @@ export function localDateKey(ms: number): string {
   return `${date.getFullYear()}-${month}-${day}`
 }
 
+/**
+ * Whether `key` is a real local-date key (`YYYY-MM-DD`). The shape check is
+ * round-tripped: an impossible date (9999-99-99) parses to NaN and a rollover
+ * (2026-02-30) lands on another day, so both would otherwise fold into a bogus,
+ * never-pruned bucket. Shared by the persisted-document reader and the day
+ * route's query gate.
+ */
+export function isLedgerDateKey(key: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(key)) return false
+  const atMs = new Date(key + 'T12:00:00').getTime()
+  return Number.isFinite(atMs) && localDateKey(atMs) === key
+}
+
 /** An empty ledger document. */
 export function createLedgerDocument(): UsageLedgerDocument {
   return { version: 1, days: {} }
@@ -152,12 +165,8 @@ export function deserializeLedger(value: unknown): UsageLedgerDocument {
   const days = (value as Record<string, unknown>).days
   if (typeof days !== 'object' || days === null) return doc
   for (const [dateKey, providers] of Object.entries(days as Record<string, unknown>)) {
-    if (!/^\d{4}-\d{2}-\d{2}$/.test(dateKey) || typeof providers !== 'object' || providers === null) continue
-    // Round-trip the date key: an impossible date (9999-99-99) parses to NaN
-    // and a rollover (2026-02-30) lands on another day; both would otherwise
-    // fold into a bogus, never-pruned bucket.
+    if (!isLedgerDateKey(dateKey) || typeof providers !== 'object' || providers === null) continue
     const atMs = new Date(dateKey + 'T12:00:00').getTime()
-    if (!Number.isFinite(atMs) || localDateKey(atMs) !== dateKey) continue
     for (const [provider, models] of Object.entries(providers as Record<string, unknown>)) {
       if (typeof models !== 'object' || models === null) continue
       for (const [model, totals] of Object.entries(models as Record<string, unknown>)) {

package/src/core/pricing.ts

@@ -4,10 +4,19 @@
  * at fold time (the provider bills each request in the period the request ran
  * in, so pricing at the fold is the honest estimate).
  *
- * Policy (api-docs.deepseek.com pricing page, effective 2026-09-10 12:00
- * Beijing): peak hours are Beijing time Monday-Friday 09:00-12:00 and
- * 14:00-18:00; every other hour (nights, weekends) is off-peak and billed at
- * half the peak price. All prices here are CNY per million tokens.
+ * Policy (api-docs.deepseek.com pricing page): peak hours are Beijing time
+ * Monday-Friday 09:00-12:00 and 14:00-18:00, excluding Chinese public
+ * holidays; every other hour is off-peak and billed at half the peak price.
+ * The published rule counts a calendar day, not the working schedule: a
+ * Saturday or Sunday is off-peak in full even on an adjusted workday, and a
+ * public holiday is off-peak in full even on a Monday-Friday. All prices
+ * here are CNY per million tokens.
+ *
+ * Public-holiday dates are not derivable from the rule, so the rule takes them as
+ * a `PublicHolidayCalendar`. The default is the published table in `./holidays.ts`,
+ * covering 2020 through ${HOLIDAY_TABLE_LAST_YEAR}; a caller with newer dates
+ * passes its own. A holiday weekday therefore prices off-peak, which is the half
+ * of the published rule that is easy to get wrong.
  *
  * The published rows are `deepseek-flash` (DeepSeek-V4.1-Flash) and
  * `deepseek-v4-pro` (DeepSeek-V4-Pro-0813). The retired flash ids
@@ -18,6 +27,7 @@
  */
 
 import type { UsageTokenTotals } from './types.ts'
+import { CHINESE_PUBLIC_HOLIDAYS, HOLIDAY_TABLE_LAST_YEAR } from './holidays.ts'
 
 /** One peak window in minutes-of-day, Beijing time. */
 interface PeakWindow {
@@ -71,32 +81,82 @@ function withinWindow(minuteOfDay: number): PeakWindow | undefined {
   return PEAK_WINDOWS.find((window) => minuteOfDay >= window.from && minuteOfDay < window.to)
 }
 
+/**
+ * Supplies the Chinese public-holiday dates the peak rule excludes. The dates
+ * are not derivable from any rule (the State Council publishes them per year),
+ * so this repository ships no table of its own: the default calendar is empty,
+ * and a caller that has real dates passes them in. A date is compared as a
+ * Beijing-time `YYYY-MM-DD` string, which is the granularity the published
+ * rule needs (a holiday is off-peak for the whole day, so times never matter).
+ */
+export interface PublicHolidayCalendar {
+  /** True when the Beijing-time calendar day `date` is a Chinese public holiday. */
+  isPublicHoliday(date: string): boolean
+}
+
+/**
+ * The default calendar: the published Chinese public-holiday table, so a holiday
+ * weekday prices off-peak instead of over-reporting at the peak rate. A year the
+ * table does not cover holds no dates and falls back to peak on weekdays, which
+ * is the safe direction to be wrong in: the estimate reads high rather than low.
+ */
+export const CN_PUBLIC_HOLIDAYS: PublicHolidayCalendar = {
+  isPublicHoliday: (date) => {
+    const year = date.slice(0, 4)
+    if (Number(year) > HOLIDAY_TABLE_LAST_YEAR) return false
+    return CHINESE_PUBLIC_HOLIDAYS[year]?.includes(date) ?? false
+  },
+}
+
+/** The Beijing-time `YYYY-MM-DD` calendar day of `ms` (UTC+8 has no DST, so the shift is exact). */
+function beijingDate(ms: number): string {
+  const shifted = new Date(ms + BEIJING_UTC_OFFSET_MS)
+  const month = `${shifted.getUTCMonth() + 1}`.padStart(2, '0')
+  const day = `${shifted.getUTCDate()}`.padStart(2, '0')
+  return `${shifted.getUTCFullYear()}-${month}-${day}`
+}
+
+/**
+ * Whether `ms` falls on a peak-eligible Beijing day: Monday-Friday that is
+ * not a public holiday. A Saturday or Sunday is never eligible, including on
+ * an adjusted workday — the provider counts the calendar day, not the
+ * working schedule.
+ */
+function isPeakDay(ms: number, calendar: PublicHolidayCalendar): boolean {
+  const shifted = new Date(ms + BEIJING_UTC_OFFSET_MS)
+  const weekday = shifted.getUTCDay()
+  if (weekday < 1 || weekday > 5) return false
+  return !calendar.isPublicHoliday(beijingDate(ms))
+}
+
 /**
  * The DeepSeek billing period at `ms`, plus when it next flips. The clock is
  * Beijing time regardless of the host timezone (UTC+8 has no DST, so a fixed
  * shift is exact). `boundaryMs` is the instant the current period ends — the
  * window's close while peaking, the next window's open otherwise.
  */
-export function deepseekPeriodAt(ms: number): { peak: boolean; boundaryMs: number } {
+export function deepseekPeriodAt(ms: number, calendar: PublicHolidayCalendar = CN_PUBLIC_HOLIDAYS): { peak: boolean; boundaryMs: number } {
   const shifted = new Date(ms + BEIJING_UTC_OFFSET_MS)
-  const weekday = shifted.getUTCDay()
   const minuteOfDay = shifted.getUTCHours() * 60 + shifted.getUTCMinutes()
-  const current = weekday >= 1 && weekday <= 5 ? withinWindow(minuteOfDay) : undefined
+  const current = isPeakDay(ms, calendar) ? withinWindow(minuteOfDay) : undefined
   if (current !== undefined) {
     return { peak: true, boundaryMs: ms + (current.to - minuteOfDay) * 60_000 - shifted.getUTCSeconds() * 1000 - shifted.getUTCMilliseconds() }
   }
-  // Next window start: later today (weekday only), else the following days'
-  // first morning window; the scan bound makes a malformed clock terminate.
+  // Next window start: later today (on a peak-eligible day), else the first
+  // peak-eligible day's morning window; the scan bound makes a malformed clock
+  // terminate.
   for (let dayOffset = 0; dayOffset < 8; dayOffset += 1) {
-    const day = new Date(ms + BEIJING_UTC_OFFSET_MS + dayOffset * 86_400_000)
-    if (day.getUTCDay() < 1 || day.getUTCDay() > 5) continue
+    const dayStartMs = ms + dayOffset * 86_400_000
+    if (!isPeakDay(dayStartMs, calendar)) continue
+    const day = new Date(dayStartMs + BEIJING_UTC_OFFSET_MS)
     const realDayStart = Date.UTC(day.getUTCFullYear(), day.getUTCMonth(), day.getUTCDate()) - BEIJING_UTC_OFFSET_MS
     for (const window of PEAK_WINDOWS) {
       if (dayOffset === 0 && window.from <= minuteOfDay) continue
       return { peak: false, boundaryMs: realDayStart + window.from * 60_000 }
     }
   }
-  // Unreachable (the scan covers a full week); a conservative off-peak answer.
+  // Unreachable (the scan covers a full week of peak-eligible days); a
+  // conservative off-peak answer.
   return { peak: false, boundaryMs: ms + 86_400_000 }
 }
 
@@ -112,12 +172,12 @@ function priceFor(model: string, atMs: number): ModelPrice {
  * row; ids from other providers never reach this function (the service gates
  * by route family). Rounded to micro-CNY so the ledger stays readable.
  */
-export function deepseekModelSpend(model: string, totals: Readonly<UsageTokenTotals>, atMs: number): number {
+export function deepseekModelSpend(model: string, totals: Readonly<UsageTokenTotals>, atMs: number, calendar: PublicHolidayCalendar = CN_PUBLIC_HOLIDAYS): number {
   const price = priceFor(model, atMs)
-  const period = deepseekPeriodAt(atMs)
+  const period = deepseekPeriodAt(atMs, calendar)
   const column = period.peak ? 'peak' : 'offPeak'
   const spend = (totals.cacheReadTokens * price.cacheHit[column]
     + (totals.inputTokens + totals.cacheWriteTokens) * price.inputMiss[column]
     + totals.outputTokens * price.output[column]) / 1_000_000
   return Math.round(spend * 1e6) / 1e6
-}
+}

package/src/core/types.ts

@@ -67,6 +67,26 @@ export interface UsageDaySummary {
   totals: UsageTokenTotals
 }
 
+/**
+ * One local day aggregated per provider and model. The overview serves today
+ * through this shape and the day route serves any retained day with it, so a
+ * day the user picks in the browser and the live today card are the same
+ * document.
+ */
+export interface UsageDayView {
+  /** Local-date key `YYYY-MM-DD`. */
+  date: string
+  totals: UsageTokenTotals
+  /** Per-provider rows, heaviest by total tokens first. */
+  providers: UsageProviderSummary[]
+}
+
+/** The day route's response body. */
+export interface UsageDayResponse {
+  ok: true
+  day: UsageDayView
+}
+
 /** A balance fact normalized from a provider probe. */
 export interface BalanceView {
   /** ISO 4217 code the provider bills in (`CNY`, `USD`, ...). */
@@ -161,9 +181,16 @@ export interface UsageOverviewView {
     today?: UsageTokenTotals
   }
   usage: {
-    today: { date: string; totals: UsageTokenTotals; providers: UsageProviderSummary[] }
+    today: UsageDayView
     /** Last N local days ascending, including today. */
     days: UsageDaySummary[]
+    /**
+     * Every retained local day that recorded usage, ascending — the day
+     * picker's option list, reaching past the trend cap to the whole
+     * retention window. Optional so an older host document still renders
+     * (the section then offers no picker).
+     */
+    availableDays?: string[]
     /**
      * The same window aggregated per provider and model — the trend card's
      * bar-chart data. Optional so an older host document still renders.

package/src/host/routes.ts

@@ -3,6 +3,8 @@ import type { Context } from '@deepseek-ai/cordis'
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import { isUsageAllowed } from './access.ts'
 import { writeJson } from './http.ts'
+import { isLedgerDateKey } from '../core/ledger.ts'
+import type { UsageDayResponse } from '../core/types.ts'
 import type { UsageService } from './usage-service.ts'
 
 export const USAGE_API_PREFIX = '/api/dsh-usage'
@@ -31,6 +33,35 @@ export function makeUsageOverviewRoute(ctx: Context, service: UsageService): Web
   }
 }
 
+/**
+ * One retained day route: `GET /api/dsh-usage/day?date=YYYY-MM-DD` answers
+ * that local day's per-provider and per-model totals, so the section's day
+ * pickers can show a past day instead of only today. Same trust fence as the
+ * overview route, and a key that is not a real local date is refused with 400
+ * rather than folded into a bogus day.
+ * @param ctx - host context; may expose remoteWebUiPairing.
+ * @param service - the usage service.
+ * @returns the route.
+ */
+export function makeUsageDayRoute(ctx: Context, service: UsageService): WebRoute {
+  return {
+    kind: 'exact',
+    path: USAGE_API_PREFIX + '/day',
+    handler: (req: IncomingMessage, res: ServerResponse): void => {
+      if (!isUsageAllowed(ctx, req)) {
+        writeJson(res, 403, { ok: false, error: 'forbidden: loopback-only' })
+        return
+      }
+      const date = new URL(req.url ?? '/', 'http://127.0.0.1').searchParams.get('date') ?? ''
+      if (!isLedgerDateKey(date)) {
+        writeJson(res, 400, { ok: false, error: 'date must be YYYY-MM-DD' })
+        return
+      }
+      writeJson(res, 200, { ok: true, day: service.day(date) } satisfies UsageDayResponse, { 'cache-control': 'no-store' })
+    },
+  }
+}
+
 /**
  * Manual refresh: forces one probe cycle now and answers with the fresh
  * overview. Same trust fence as the overview route.

package/src/host/usage-service.ts

@@ -20,7 +20,7 @@ import type { BalanceParse, PlanParse } from '../core/adapters.ts'
 import { foldAliasRoutes } from '../core/provider-routes.ts'
 import { deepseekModelSpend } from '../core/pricing.ts'
 import { createLedgerDocument, deserializeLedger, foldUsage, ledgerDayKeys, localDateKey, pruneLedger, summarizeDays, totalTokens } from '../core/ledger.ts'
-import type { BalanceView, CredentialKind, ObservedSpendView, PlanView, ProviderSnapshotState, ProviderSnapshotView, UsageLedgerDocument, UsageOverviewView, UsageTokenTotals } from '../core/types.ts'
+import type { BalanceView, CredentialKind, ObservedSpendView, PlanView, ProviderSnapshotState, ProviderSnapshotView, UsageDayView, UsageLedgerDocument, UsageOverviewView, UsageTokenTotals } from '../core/types.ts'
 import { addTotals, emptyTotals } from '../core/types.ts'
 
 /**
@@ -350,6 +350,9 @@ export class UsageService {
           totals: range.totals,
           providers: range.providers,
         },
+        // Every retained day, not just the trend window: the day picker's
+        // option list reaches back to the oldest day retention still keeps.
+        availableDays: allKeys,
         all: {
           from: allKeys[0] ?? todayKey,
           to: allKeys[allKeys.length - 1] ?? todayKey,
@@ -393,8 +396,19 @@ export class UsageService {
     }
   }
 
+  /**
+   * One retained local day aggregated per provider and model, as the day
+   * route serves it. A day the ledger never held — pruned by retention, or
+   * simply without usage — reads as a zeroed day rather than an error, so a
+   * picker selection that aged out degrades to "no usage" instead of a broken
+   * panel. The route gates the key's shape before it gets here.
+   */
+  day(dateKey: string): UsageDayView {
+    return this.daySummary(dateKey)
+  }
+
   /** One local day aggregated per provider. */
-  private daySummary(dateKey: string): UsageOverviewView['usage']['today'] {
+  private daySummary(dateKey: string): UsageDayView {
     const day = this.ledger.days[dateKey] ?? {}
     const { totals, providers } = summarizeDays([day])
     return { date: dateKey, totals, providers }

package/src/index.ts

@@ -4,7 +4,7 @@ import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
 import z from '@deepseek-ai/schemastery'
 import { mountOnce } from './mount-once.ts'
 import { UsageService, type UsageServiceOptions } from './host/usage-service.ts'
-import { makeUsageOverviewRoute, makeUsageRefreshRoute } from './host/routes.ts'
+import { makeUsageDayRoute, makeUsageOverviewRoute, makeUsageRefreshRoute } from './host/routes.ts'
 
 declare module '@deepseek-ai/cordis' {
   interface Events {
@@ -126,9 +126,9 @@ export const apply = mountOnce('@linxin666/dsh-usage', (ctx: Context, config?: U
   /** True while this activation has a start queued behind a predecessor's flush. */
   let queued = false
 
-  /** Register the service's two routes; the returned disposer unregisters them. */
+  /** Register the service's routes; the returned disposer unregisters them. */
   const mountRoutes = (next: UsageService): (() => void) => {
-    const disposers = [makeUsageOverviewRoute(ctx, next), makeUsageRefreshRoute(ctx, next)]
+    const disposers = [makeUsageOverviewRoute(ctx, next), makeUsageDayRoute(ctx, next), makeUsageRefreshRoute(ctx, next)]
       .map((route) => ctx.webServer.register(route))
     return () => {
       for (const dispose of disposers) {