@linxin666/dsh-usage 0.4.4 → 0.4.5

package/lib/index.js

@@ -118,7 +118,7 @@ function mountOnce(packageName, fn) {
 	return mount;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/@deepseek-ai+dsh-brand@0.2.0-rc.1_@deepseek-ai+cordis@4.0.4/node_modules/@deepseek-ai/dsh-brand/lib/index.js
+//#region ../../node_modules/.pnpm/@deepseek-ai+dsh-brand@0.2.0-rc.2_@deepseek-ai+cordis@4.0.4/node_modules/@deepseek-ai/dsh-brand/lib/index.js
 /**
 * Duplicate-install-safe nominal primitive helpers.
 *
@@ -141,7 +141,7 @@ function brandString(value) {
 	return value;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/@deepseek-ai+dsh-credentials@0.2.0-rc.1_@deepseek-ai+cordis@4.0.4_@deepseek-ai+dsh-inva_1a647ad178a224e363f109a5f72e2237/node_modules/@deepseek-ai/dsh-credentials/lib/index.js
+//#region ../../node_modules/.pnpm/@deepseek-ai+dsh-credentials@0.2.0-rc.2_@deepseek-ai+cordis@4.0.4_@deepseek-ai+dsh-inva_13783eb73d2217c5a4a149b781a9cc49/node_modules/@deepseek-ai/dsh-credentials/lib/index.js
 /**
 * Service Definition for the credential-reference capability seam (`ctx.credentials`). Settings and composition files carry
 * *references* to secrets — environment-variable names — while providers own
@@ -310,6 +310,7 @@ function bearer(apiKey) {
 }
 const DEEPSEEK = {
 	ids: ["deepseek", "deepseek-official"],
+	familyOnlyIds: ["deepseek-account"],
 	displayName: "DeepSeek",
 	balance: {
 		origin: "https://api.deepseek.com",
@@ -729,11 +730,20 @@ function balanceAppliesToRoute(adapter, baseURL) {
 /**
 * Whether a provider route belongs to the official DeepSeek family: the only
 * family with a spend price book and a settings-section-owned env credential
-* (llm-deepseek) rather than a pi-ai profile. Drives the env fallback in
-* credential resolution and the fold-time cost stamping.
+* (llm-deepseek) rather than a pi-ai profile. Drives the fold-time cost
+* stamping, the client fold-time spend estimate, and the whale-yuan bank.
+*
+* Family membership is wider than the probe directory. The account route
+* (deepseek-account) bills the same account but authenticates with the account
+* token, so it prices and mints while `adapterFor()` still returns undefined
+* for it and no probe or env-credential fallback can reach it. Every caller of
+* this predicate is an accounting decision; the credential and probing
+* decisions read `adapterFor()` instead, so the two never widen together
+* (issue #1772).
 */
 function isDeepSeekProviderRoute(provider) {
-	return adapterFor(provider) === DEEPSEEK;
+	if (adapterFor(provider) === DEEPSEEK) return true;
+	return DEEPSEEK.familyOnlyIds?.includes(provider) === true;
 }
 /**
 * Best-effort human message from a provider error body, for the per-provider
@@ -777,6 +787,252 @@ function foldAliasRoutes(routes) {
 	});
 }
 //#endregion
+//#region src/core/holidays.ts
+/**
+* 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. */
+const CHINESE_PUBLIC_HOLIDAYS = {
+	"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"
+	]
+};
+//#endregion
 //#region src/core/pricing.ts
 /** The published peak windows: weekday 09:00-12:00 and 14:00-18:00. */
 const PEAK_WINDOWS = [{
@@ -828,23 +1084,52 @@ function withinWindow(minuteOfDay) {
 	return PEAK_WINDOWS.find((window) => minuteOfDay >= window.from && minuteOfDay < window.to);
 }
 /**
+* 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.
+*/
+const CN_PUBLIC_HOLIDAYS = { isPublicHoliday: (date) => {
+	const year = date.slice(0, 4);
+	if (Number(year) > 2026) 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) {
+	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, calendar) {
+	const weekday = new Date(ms + BEIJING_UTC_OFFSET_MS).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.
 */
-function deepseekPeriodAt(ms) {
+function deepseekPeriodAt(ms, calendar = CN_PUBLIC_HOLIDAYS) {
 	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) : void 0;
+	const current = isPeakDay(ms, calendar) ? withinWindow(minuteOfDay) : void 0;
 	if (current !== void 0) return {
 		peak: true,
 		boundaryMs: ms + (current.to - minuteOfDay) * 6e4 - shifted.getUTCSeconds() * 1e3 - shifted.getUTCMilliseconds()
 	};
 	for (let dayOffset = 0; dayOffset < 8; dayOffset += 1) {
-		const day = new Date(ms + BEIJING_UTC_OFFSET_MS + dayOffset * 864e5);
-		if (day.getUTCDay() < 1 || day.getUTCDay() > 5) continue;
+		const dayStartMs = ms + dayOffset * 864e5;
+		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;
@@ -869,9 +1154,9 @@ function priceFor(model, atMs) {
 * row; ids from other providers never reach this function (the service gates
 * by route family). Rounded to micro-CNY so the ledger stays readable.
 */
-function deepseekModelSpend(model, totals, atMs) {
+function deepseekModelSpend(model, totals, atMs, calendar = CN_PUBLIC_HOLIDAYS) {
 	const price = priceFor(model, atMs);
-	const column = deepseekPeriodAt(atMs).peak ? "peak" : "offPeak";
+	const column = deepseekPeriodAt(atMs, calendar).peak ? "peak" : "offPeak";
 	const spend = (totals.cacheReadTokens * price.cacheHit[column] + (totals.inputTokens + totals.cacheWriteTokens) * price.inputMiss[column] + totals.outputTokens * price.output[column]) / 1e6;
 	return Math.round(spend * 1e6) / 1e6;
 }
@@ -915,6 +1200,18 @@ function localDateKey(ms) {
 	const day = String(date.getDate()).padStart(2, "0");
 	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.
+*/
+function isLedgerDateKey(key) {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(key)) return false;
+	const atMs = (/* @__PURE__ */ new Date(key + "T12:00:00")).getTime();
+	return Number.isFinite(atMs) && localDateKey(atMs) === key;
+}
 /** An empty ledger document. */
 function createLedgerDocument() {
 	return {
@@ -1041,9 +1338,8 @@ function deserializeLedger(value) {
 	const days = value.days;
 	if (typeof days !== "object" || days === null) return doc;
 	for (const [dateKey, providers] of Object.entries(days)) {
-		if (!/^\d{4}-\d{2}-\d{2}$/.test(dateKey) || typeof providers !== "object" || providers === null) continue;
+		if (!isLedgerDateKey(dateKey) || typeof providers !== "object" || providers === null) continue;
 		const atMs = (/* @__PURE__ */ new Date(dateKey + "T12:00:00")).getTime();
-		if (!Number.isFinite(atMs) || localDateKey(atMs) !== dateKey) continue;
 		for (const [provider, models] of Object.entries(providers)) {
 			if (typeof models !== "object" || models === null) continue;
 			for (const [model, totals] of Object.entries(models)) {
@@ -1275,6 +1571,7 @@ var UsageService = class {
 					totals: range.totals,
 					providers: range.providers
 				},
+				availableDays: allKeys,
 				all: {
 					from: allKeys[0] ?? todayKey,
 					to: allKeys[allKeys.length - 1] ?? todayKey,
@@ -1315,6 +1612,16 @@ var UsageService = class {
 			...today.calls > 0 && totalTokens(today) > 0 ? { today } : {}
 		};
 	}
+	/**
+	* 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) {
+		return this.daySummary(dateKey);
+	}
 	/** One local day aggregated per provider. */
 	daySummary(dateKey) {
 		const { totals, providers } = summarizeDays([this.ledger.days[dateKey] ?? {}]);
@@ -1798,6 +2105,43 @@ function makeUsageOverviewRoute(ctx, service) {
 	};
 }
 /**
+* 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.
+*/
+function makeUsageDayRoute(ctx, service) {
+	return {
+		kind: "exact",
+		path: "/api/dsh-usage/day",
+		handler: (req, res) => {
+			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)
+			}, { "cache-control": "no-store" });
+		}
+	};
+}
+/**
 * Manual refresh: forces one probe cycle now and answers with the fresh
 * overview. Same trust fence as the overview route.
 * @param ctx - host context; may expose remoteWebUiPairing.
@@ -1913,9 +2257,13 @@ const apply = mountOnce("@linxin666/dsh-usage", (ctx, config) => {
 	let disposeRoutes;
 	/** 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) => {
-		const disposers = [makeUsageOverviewRoute(ctx, next), makeUsageRefreshRoute(ctx, next)].map((route) => ctx.webServer.register(route));
+		const disposers = [
+			makeUsageOverviewRoute(ctx, next),
+			makeUsageDayRoute(ctx, next),
+			makeUsageRefreshRoute(ctx, next)
+		].map((route) => ctx.webServer.register(route));
 		return () => {
 			for (const dispose of disposers) try {
 				dispose();

package/lib/types/client/UsageSectionCard.d.ts

@@ -10,6 +10,7 @@
 import { type ReactNode } from 'react';
 import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
 import type { UsageStoreInstance } from './usage-store.ts';
+import type { UsageDayView } from '../core/types.ts';
 /** The settings fields this section edits (immediate-apply semantics). */
 export interface UsageSettings {
     enabled?: boolean;
@@ -23,6 +24,12 @@ export interface UsageSectionFace {
     poll: () => void;
     /** Force a host probe cycle now (resolves with the fresh overview). */
     refresh: () => void;
+    /**
+     * Fetch one retained local day (YYYY-MM-DD) from the host. The overview
+     * only carries today plus the list of recorded days, so a day the user picks
+     * is one small on-demand request.
+     */
+    loadDay: (date: string) => Promise<UsageDayView>;
     /** The shared configuration form this section's settings row reads and writes. */
     settings: ConfigForm<UsageSettings>;
 }

package/lib/types/client/locales.d.ts

@@ -20,6 +20,13 @@ export declare const zh: {
     'usage.current': string;
     'usage.today': string;
     'usage.today.cost': string;
+    'usage.day.label': string;
+    'usage.day.today': string;
+    'usage.day.title': string;
+    'usage.day.cost': string;
+    'usage.day.empty': string;
+    'usage.day.loading': string;
+    'usage.day.error': string;
     'usage.peak.on': string;
     'usage.peak.off': string;
     'usage.calls': string;
@@ -54,6 +61,7 @@ export declare const zh: {
     'usage.bank.spend.observed': string;
     'usage.bank.spend.estimated': string;
     'usage.bank.window': string;
+    'usage.bank.windowAll': string;
     'usage.bank.save': string;
     'usage.bank.share': string;
     'usage.bank.drawError': string;

package/lib/types/core/adapters.d.ts

@@ -42,6 +42,24 @@ export interface PlanParse {
 export interface ProviderAdapter {
     /** Provider route keys this adapter serves. */
     ids: readonly string[];
+    /**
+     * Route keys that belong to this family for accounting (token folding, the
+     * spend price book, the whale-yuan bank) but must never be probed with this
+     * adapter's endpoints.
+     *
+     * A route reaches the DeepSeek family without an API key when the user is
+     * signed in to a DeepSeek account: the llm-deepseek-account plugin registers
+     * the route id deepseek-account, which authenticates with the account token
+     * rather than a key. Its tokens bill the same account the official route
+     * bills, so the family must own it, but the balance endpoint reads an
+     * API-key account: probing it would either fail on the account token or,
+     * when the user also configured DEEPSEEK_API_KEY, print the API-key account's
+     * money under the account route's name (issue #1772, the same
+     * mis-attribution class as #1688). adapterFor() deliberately does not
+     * resolve these ids, so no probe, credential fallback, or alias fold can
+     * reach them; family membership is read through isDeepSeekProviderRoute().
+     */
+    familyOnlyIds?: readonly string[];
     /** Fallback display name when the LLM runtime has none. */
     displayName: string;
     balance?: {
@@ -101,8 +119,16 @@ export declare function balanceAppliesToRoute(adapter: ProviderAdapter, baseURL:
 /**
  * Whether a provider route belongs to the official DeepSeek family: the only
  * family with a spend price book and a settings-section-owned env credential
- * (llm-deepseek) rather than a pi-ai profile. Drives the env fallback in
- * credential resolution and the fold-time cost stamping.
+ * (llm-deepseek) rather than a pi-ai profile. Drives the fold-time cost
+ * stamping, the client fold-time spend estimate, and the whale-yuan bank.
+ *
+ * Family membership is wider than the probe directory. The account route
+ * (deepseek-account) bills the same account but authenticates with the account
+ * token, so it prices and mints while `adapterFor()` still returns undefined
+ * for it and no probe or env-credential fallback can reach it. Every caller of
+ * this predicate is an accounting decision; the credential and probing
+ * decisions read `adapterFor()` instead, so the two never widen together
+ * (issue #1772).
  */
 export declare function isDeepSeekProviderRoute(provider: string): boolean;
 /**

package/lib/types/core/holidays.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 declare const CHINESE_PUBLIC_HOLIDAYS: Readonly<Record<string, readonly string[]>>;
+/** The newest year this table covers; later years carry no entry. */
+export declare const HOLIDAY_TABLE_LAST_YEAR = 2026;

package/lib/types/core/ledger.d.ts

@@ -7,6 +7,14 @@
 import { type UsageLedgerDocument, type UsageProviderSummary, type UsageTokenTotals } from './types.ts';
 /** Local-date key (`YYYY-MM-DD`) for an epoch ms timestamp. */
 export declare function localDateKey(ms: number): string;
+/**
+ * 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 declare function isLedgerDateKey(key: string): boolean;
 /** An empty ledger document. */
 export declare function createLedgerDocument(): UsageLedgerDocument;
 /**

package/lib/types/core/pricing.d.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
@@ -17,13 +26,32 @@
  * @module @linxin666/dsh-usage/core/pricing
  */
 import type { UsageTokenTotals } from './types.ts';
+/**
+ * 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 declare const CN_PUBLIC_HOLIDAYS: PublicHolidayCalendar;
 /**
  * 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 declare function deepseekPeriodAt(ms: number): {
+export declare function deepseekPeriodAt(ms: number, calendar?: PublicHolidayCalendar): {
     peak: boolean;
     boundaryMs: number;
 };
@@ -33,4 +61,4 @@ export declare function deepseekPeriodAt(ms: number): {
  * 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 declare function deepseekModelSpend(model: string, totals: Readonly<UsageTokenTotals>, atMs: number): number;
+export declare function deepseekModelSpend(model: string, totals: Readonly<UsageTokenTotals>, atMs: number, calendar?: PublicHolidayCalendar): number;