@kenz1117/dsh-ui-usage-billing 0.2.1 → 0.2.3

package/lib/index.js

@@ -1,27 +1,11 @@
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-//#region lib/types/client/pricing.js
-/**
-* Billing engine: per-model price tables and token-usage cost estimation.
-*
-* Each model's price table uses its NATIVE currency: domestic providers
-* (DeepSeek, 智谱, 通义…) publish RMB prices and store them directly;
-* overseas providers (OpenAI, Google, xAI, Meta) publish USD.
-* Cost is always computed and displayed in CNY — only USD-priced models go
-* through the exchange rate, never domestic ones.
-*
-* Google-style two-band billing is modeled per model: Gemini's Flex tier
-* prices spare-capacity traffic at -50%; DeepSeek V4 splits peak
-* (09:00-12:00 / 14:00-18:00 Beijing) at 2x the off-peak rate. The estimator
-* mixes both bands by a configured peak share ({@link DEFAULT_PEAK_SHARE}).
-*/
-/**
-* USD → CNY rate for display. Source: China Foreign Exchange Trade System
-* mid-rate 6.7878 on 2026-08-14; rounded to 6.79. Only applies to overseas
-* USD-priced models — domestic models never pass through this rate.
-*/
-const USD_TO_CNY = 6.79;
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+/** 当前汇率：实时覆盖优先，缺省回退内置固定值。 */
+function currentRate() {
+	return 6.79;
+}
 /** Default share of traffic assumed to fall in the peak band (0..1). */
 const DEFAULT_PEAK_SHARE = .5;
 /**
@@ -500,11 +484,11 @@ const MODEL_CATALOG = [
 ];
 /** Lookup a model by its stats key; falls back to the generic `other` entry. */
 function modelOf(key) {
-	const found = MODEL_CATALOG.find((entry) => entry.key === key);
-	if (found !== void 0) return found;
-	const fallback = MODEL_CATALOG.at(-1);
-	if (fallback !== void 0) return fallback;
-	throw new Error("MODEL_CATALOG must not be empty");
+	return MODEL_CATALOG.find((entry) => entry.key === key) ?? (() => {
+		const fallback = MODEL_CATALOG.at(-1);
+		if (fallback !== void 0) return fallback;
+		throw new Error("MODEL_CATALOG must not be empty");
+	})();
 }
 /**
 * Price one band's token usage in CNY. The stats `input` field is the TOTAL
@@ -518,12 +502,18 @@ function priceBandCost(band, buckets, currency) {
 	const miss = buckets.cacheMiss > 0 ? buckets.cacheMiss : Math.max(0, buckets.input - buckets.cacheHit);
 	const hit = Math.min(buckets.cacheHit, buckets.input);
 	const raw = (miss * (band.cacheMiss ?? band.input) + hit * band.cacheHit + buckets.output * band.output) / 1e6;
-	return currency === "USD" ? raw * USD_TO_CNY : raw;
+	return currency === "USD" ? raw * currentRate() : raw;
 }
 /**
 * Estimate the CNY cost of one model's token usage, mixing the peak and
 * off-peak bands by the given peak share (flat-priced models cost the same in
 * both bands).
+*
+* 计费维度是「缓存命中价 × 时段价」的交叉：每个时段档内部分别按缓存命中
+* 价（cacheHit）与未命中价（input/cacheMiss）计价，两个时段档再按
+* peakShare 混合。时段定义以北京时间为准（如 DeepSeek V4 高峰
+* 09:00-12:00 / 14:00-18:00）。因聚合只有按日 token 量、没有请求级时间戳，
+* 时段只能按比例估算，而非逐请求判定。
 * @param entry - the catalog entry whose prices apply.
 * @param buckets - token usage counts.
 * @param peakShare - share of traffic in the peak band (0..1); defaults to {@link DEFAULT_PEAK_SHARE}.
@@ -673,6 +663,253 @@ async function aggregateUsage(persistence, options = {}) {
 	};
 }
 //#endregion
+//#region lib/types/balance.js
+/**
+* Account-balance queries for the billing dashboard.
+*
+* Only providers with a public balance endpoint can report one. Today that is
+* DeepSeek (`GET https://api.deepseek.com/user/balance`, Bearer 鉴权); the
+* other mainstream providers (OpenAI, 智谱, 通义, Kimi…) expose no standard
+* balance API, so their rows in the model table show an unavailable state.
+* The lookup map below is the extension point for future providers.
+*/
+/** Abort a balance fetch when the upstream hangs beyond this budget. */
+const FETCH_TIMEOUT_MS$1 = 8e3;
+/** DeepSeek 官方余额接口（官方文档 api-docs.deepseek.com/api/get-user-balance）。 */
+const DEEPSEEK_BALANCE_URL = "https://api.deepseek.com/user/balance";
+/** 数字归一化：接口返回的余额是字符串（如 `"110.00"`），统一转 number。 */
+function toNumber(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string") {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : void 0;
+	}
+}
+/**
+* Query the DeepSeek account balance through the configured credential.
+* @param ctx - host context carrying the credentials seam.
+* @param apiKeyEnv - credential reference resolving the DeepSeek API key.
+* @returns the balance row, or an error row when the key/endpoint misbehaves.
+*/
+async function queryDeepSeek(ctx, apiKeyEnv) {
+	const hit = await ctx.credentials.resolve(credentialRef(apiKeyEnv));
+	if (hit === void 0) return {
+		provider: "deepseek",
+		displayName: "DeepSeek",
+		error: "unconfigured"
+	};
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS$1);
+	try {
+		const response = await fetch(DEEPSEEK_BALANCE_URL, {
+			headers: {
+				accept: "application/json",
+				authorization: `Bearer ${hit.value}`
+			},
+			signal: controller.signal
+		});
+		if (response.status === 401 || response.status === 403) return {
+			provider: "deepseek",
+			displayName: "DeepSeek",
+			error: "unauthorized"
+		};
+		if (!response.ok) return {
+			provider: "deepseek",
+			displayName: "DeepSeek",
+			error: "unreachable"
+		};
+		const data = await response.json();
+		const info = (Array.isArray(data.balance_infos) ? data.balance_infos : [])[0];
+		const currency = typeof info?.currency === "string" ? info.currency : void 0;
+		const totalBalance = toNumber(info?.total_balance);
+		const grantedBalance = toNumber(info?.granted_balance);
+		const toppedUpBalance = toNumber(info?.topped_up_balance);
+		const isAvailable = typeof data.is_available === "boolean" ? data.is_available : void 0;
+		return {
+			provider: "deepseek",
+			displayName: "DeepSeek",
+			...currency !== void 0 ? { currency } : {},
+			...totalBalance !== void 0 ? { totalBalance } : {},
+			...grantedBalance !== void 0 ? { grantedBalance } : {},
+			...toppedUpBalance !== void 0 ? { toppedUpBalance } : {},
+			...isAvailable !== void 0 ? { isAvailable } : {}
+		};
+	} catch {
+		return {
+			provider: "deepseek",
+			displayName: "DeepSeek",
+			error: "unreachable"
+		};
+	} finally {
+		clearTimeout(timer);
+	}
+}
+const QUERIERS = [{
+	provider: "deepseek",
+	querier: queryDeepSeek
+}];
+/**
+* Query every configured provider's account balance.
+* @param ctx - host context carrying the credentials seam.
+* @param balanceApiKeyEnv - credential reference for the DeepSeek key.
+* @returns the balance rows (one per provider).
+*/
+async function queryBalances(ctx, balanceApiKeyEnv) {
+	return await Promise.all(QUERIERS.map(({ querier }) => querier(ctx, balanceApiKeyEnv)));
+}
+//#endregion
+//#region lib/types/pricing-fetch.js
+/**
+* One-shot live pricing refresh for the billing dashboard.
+*
+* Fetches the USD → CNY mid rate and the OpenRouter model price list, maps
+* matched models onto the built-in catalog keys, and returns the combined
+* LivePricing. Every fetch failure degrades to the built-in values: the node
+* half caches whatever succeeded and the browser dashboard falls back to the
+* catalog for the rest — a total outage answers `{ source: 'builtin' }`.
+*/
+/** Abort a fetch when the upstream hangs beyond this budget. */
+const FETCH_TIMEOUT_MS = 8e3;
+/**
+* USD → CNY 汇率源，按顺序尝试：国内可达的腾讯财经行情（免 key、`~` 分隔
+* 第 4 个字段为价格）优先，国外 open.er-api.com 兜底。任一源失败自动落到
+* 下一个；全部失败由调用方降级内置汇率。
+*/
+const RATE_SOURCES = [{
+	url: "https://qt.gtimg.cn/q=whUSDCNY",
+	parse: (text) => {
+		const price = /"([^"]*)"/.exec(text)?.[1]?.split("~")[3];
+		return price !== void 0 && price !== "" ? Number(price) : void 0;
+	}
+}, {
+	url: "https://open.er-api.com/v6/latest/USD",
+	parse: (text) => {
+		try {
+			const cny = JSON.parse(text).rates?.CNY;
+			return typeof cny === "number" && Number.isFinite(cny) && cny > 0 ? cny : void 0;
+		} catch {
+			return;
+		}
+	}
+}];
+/** OpenRouter's public model list: per-token USD prices, no key needed. */
+const ROUTER_URL = "https://openrouter.ai/api/v1/models";
+/**
+* Built-in catalog key → OpenRouter model-id candidates. Matching prefers an
+* exact id, then a single strong substring hit (the router id contains the
+* hint); an ambiguous hit is skipped so the built-in price stays
+* authoritative. Hints are provider+generation words the router ids carry —
+* correct or extend them as the market moves.
+*/
+const ROUTER_ID_HINTS = {
+	"flash": ["deepseek-v4-flash", "deepseek-v4"],
+	"pro": ["deepseek-v4-pro"],
+	"glm": ["glm-5"],
+	"qwen-3.8-max": ["qwen-3.8-max", "qwen3.8-max"],
+	"qwen-max": ["qwen-max"],
+	"qwen-plus": ["qwen-plus"],
+	"gemini-pro": ["gemini-3-pro", "gemini-pro"],
+	"gemini-flash": ["gemini-3-flash", "gemini-flash"],
+	"gpt-5.6-sol": ["gpt-5.6-sol"],
+	"gpt-5.6-terra": ["gpt-5.6-terra"],
+	"gpt-5.6-luna": ["gpt-5.6-luna"],
+	"grok": ["grok-4"],
+	"llama": ["llama-4"],
+	"kimi": ["kimi-k2"]
+};
+/** GET a URL's text body with a hard timeout; null on any failure. */
+async function fetchText(url) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+	try {
+		const response = await fetch(url, { signal: controller.signal });
+		if (!response.ok) return null;
+		return await response.text();
+	} catch {
+		return null;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/** GET a JSON endpoint with a hard timeout; null on any failure. */
+async function fetchJson(url) {
+	const text = await fetchText(url);
+	if (text === null) return null;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+}
+/** Latest USD → CNY rate from the first working source, or undefined when none respond. */
+async function fetchRate() {
+	for (const source of RATE_SOURCES) {
+		const text = await fetchText(source.url);
+		if (text === null) continue;
+		const value = source.parse(text);
+		if (value !== void 0 && Number.isFinite(value) && value > 0) return value;
+	}
+}
+/** OpenRouter model rows with usable USD unit prices, or undefined on failure. */
+async function fetchRouterModels() {
+	const data = await fetchJson(ROUTER_URL);
+	if (data === null || typeof data !== "object") return void 0;
+	const list = data.data;
+	if (!Array.isArray(list)) return void 0;
+	const models = [];
+	for (const item of list) {
+		if (item === null || typeof item !== "object") continue;
+		const { id, pricing } = item;
+		if (typeof id !== "string" || pricing === null || typeof pricing !== "object") continue;
+		const { prompt, completion } = pricing;
+		if (typeof prompt !== "number" || typeof completion !== "number") continue;
+		if (!Number.isFinite(prompt) || !Number.isFinite(completion)) continue;
+		models.push({
+			id,
+			input: prompt * 1e6,
+			output: completion * 1e6
+		});
+	}
+	return models;
+}
+/** Match one catalog key's candidates: exact id first, then a single strong substring hit. */
+function matchRouterModel(hints, models) {
+	const exact = models.find((model) => hints.some((hint) => model.id === hint));
+	if (exact !== void 0) return exact;
+	const strong = models.filter((model) => hints.some((hint) => hint.length >= 8 && model.id.includes(hint)));
+	if (strong.length !== 1) return void 0;
+	return strong[0];
+}
+/** Map router matches onto catalog keys; undefined when nothing matched. */
+function buildPrices(models) {
+	const result = {};
+	for (const [key, hints] of Object.entries(ROUTER_ID_HINTS)) {
+		const hit = matchRouterModel(hints, models);
+		if (hit === void 0) continue;
+		result[key] = {
+			input: hit.input,
+			cacheHit: hit.input * .1,
+			output: hit.output
+		};
+	}
+	return Object.keys(result).length > 0 ? result : void 0;
+}
+/**
+* Fetch the live pricing once at boot. Both upstreams run in parallel; a
+* failure in either degrades independently to the built-in value.
+* @returns the live pricing snapshot (builtin when everything failed).
+*/
+async function fetchLivePricing() {
+	const [rate, models] = await Promise.all([fetchRate(), fetchRouterModels()]);
+	const prices = models === void 0 ? void 0 : buildPrices(models);
+	if (rate === void 0 && prices === void 0) return { source: "builtin" };
+	return {
+		source: "live",
+		...rate !== void 0 ? { rate } : {},
+		...prices !== void 0 ? { prices } : {}
+	};
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Usage billing surface plugin, node half.
@@ -685,8 +922,16 @@ async function aggregateUsage(persistence, options = {}) {
 * missing file answers `{ error }` so the dashboard shows zeros, never
 * fabricated samples.
 */
+/** 实时定价的后台刷新间隔（毫秒）：汇率/模型价低频变化，6 小时一次足够。 */
+const PRICING_REFRESH_INTERVAL_MS = 360 * 60 * 1e3;
+/** DeepSeek 余额查询的默认凭据引用（与 llm-deepseek 的默认引用一致）。 */
+const DEFAULT_BALANCE_API_KEY_ENV = "DEEPSEEK_API_KEY";
 /** Required services: the web server and the persisted session log store. */
-const inject = ["webServer", "sessionPersistence"];
+const inject = [
+	"webServer",
+	"sessionPersistence",
+	"credentials"
+];
 /**
 * Host plugin body: serve real aggregated usage to the browser dashboard.
 * @param ctx - host context carrying webServer and sessionPersistence.
@@ -700,6 +945,36 @@ function apply(ctx, config = {}) {
 		join(cwd, ".dsh-usage-stats.json"),
 		join(homedir(), ".dsh/.dsh-usage-stats.json")
 	].filter((path) => typeof path === "string" && path.length > 0);
+	let live = { source: "builtin" };
+	const refreshPricing = async () => {
+		live = await fetchLivePricing();
+	};
+	refreshPricing();
+	ctx.effect(() => {
+		const timer = setInterval(() => {
+			refreshPricing();
+		}, PRICING_REFRESH_INTERVAL_MS);
+		return () => {
+			clearInterval(timer);
+		};
+	}, "usage-billing: pricing refresh timer");
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/api/billing/pricing",
+		handler: async (_req, res) => {
+			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+			res.end(JSON.stringify(live));
+		}
+	}), "usage-billing: pricing route");
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/api/billing/balance",
+		handler: async (_req, res) => {
+			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+			const balances = await queryBalances(ctx, config.balanceApiKeyEnv ?? DEFAULT_BALANCE_API_KEY_ENV);
+			res.end(JSON.stringify({ balances }));
+		}
+	}), "usage-billing: balance route");
 	ctx.effect(() => ctx.webServer.register({
 		kind: "exact",
 		path: "/api/billing/usage-stats",

package/lib/types/balance.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Account-balance queries for the billing dashboard.
+ *
+ * Only providers with a public balance endpoint can report one. Today that is
+ * DeepSeek (`GET https://api.deepseek.com/user/balance`, Bearer 鉴权); the
+ * other mainstream providers (OpenAI, 智谱, 通义, Kimi…) expose no standard
+ * balance API, so their rows in the model table show an unavailable state.
+ * The lookup map below is the extension point for future providers.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ProviderBalance } from './pricing-shared.ts';
+/**
+ * Query every configured provider's account balance.
+ * @param ctx - host context carrying the credentials seam.
+ * @param balanceApiKeyEnv - credential reference for the DeepSeek key.
+ * @returns the balance rows (one per provider).
+ */
+export declare function queryBalances(ctx: Context, balanceApiKeyEnv: string): Promise<readonly ProviderBalance[]>;
+//# sourceMappingURL=balance.d.ts.map

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

@@ -1,9 +1,11 @@
 /**
- * TrendChart: dependency-free SVG stacked bar chart of daily cost per model.
- * Each day's column stacks every model's share in its brand color, so the
- * total trend and the per-model composition are visible at once. A hover
- * crosshair shows the day's model breakdown. No chart library — the surface
- * stays self-contained and offline.
+ * TrendChart: dependency-free SVG chart of daily cost + calls.
+ *
+ * The columns are GROUPED per model — one bar per model per day, each in its
+ * brand color, so per-model cost is directly comparable. The blue line is the
+ * total call volume across all models, plotted on its own right-hand axis.
+ * A hover crosshair shows the day's model breakdown. No chart library — the
+ * surface stays self-contained and offline.
  */
 /** One model's legend identity: key, display name, and brand color. */
 export interface TrendSeriesModel {
@@ -11,7 +13,7 @@ export interface TrendSeriesModel {
     key: string;
     /** Human-readable model name. */
     name: string;
-    /** Resolved brand color for the stack segment and legend swatch. */
+    /** Resolved brand color for the bar and legend swatch (empty = single-color fallback). */
     color: string;
 }
 /** One day row fed to the chart. */
@@ -20,15 +22,15 @@ export interface TrendPoint {
     date: string;
     /** Total cost that day. */
     cost: number;
-    /** API calls that day. */
+    /** API calls that day (total across models). */
     calls: number;
-    /** Per-model cost that day (stats key → CNY); absent entries stack zero. */
+    /** Per-model cost that day (stats key → CNY); absent entries plot zero. */
     byModel?: Readonly<Record<string, number>>;
 }
 /**
- * Render the daily per-model stacked cost chart.
+ * Render the daily grouped cost bars plus the total-calls line.
  * @param props.data - sorted daily rows (ascending date).
- * @param props.models - the model legend, in stack order (bottom first).
+ * @param props.models - the model legend, in bar order.
  */
 export declare function TrendChart({ data, models }: {
     data: readonly TrendPoint[];

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

@@ -1,5 +1,5 @@
 /** Locale dictionaries for the usage billing surface. */
-export type UsageBillingKey = 'billing.title' | 'billing.subtitle' | 'billing.cost' | 'billing.todayCost' | 'billing.monthCost' | 'billing.yearCost' | 'billing.totalCost' | 'billing.calls' | 'billing.cacheHitRate' | 'billing.tokens' | 'billing.inputTokens' | 'billing.outputTokens' | 'billing.avgCost' | 'billing.trend' | 'billing.trendEmpty' | 'billing.models' | 'billing.estimated' | 'billing.actual' | 'billing.pricing' | 'billing.showPricing' | 'billing.hidePricing' | 'billing.pricePerM' | 'billing.input' | 'billing.output' | 'billing.cacheHit' | 'billing.peak' | 'billing.offPeak' | 'billing.flat' | 'billing.peakHours' | 'billing.band' | 'billing.openDashboard' | 'billing.close' | 'billing.lastUpdated' | 'billing.noData';
+export type UsageBillingKey = 'billing.title' | 'billing.subtitle' | 'billing.cost' | 'billing.todayCost' | 'billing.monthCost' | 'billing.yearCost' | 'billing.totalCost' | 'billing.calls' | 'billing.cacheHitRate' | 'billing.tokens' | 'billing.inputTokens' | 'billing.outputTokens' | 'billing.avgCost' | 'billing.trend' | 'billing.trendEmpty' | 'billing.models' | 'billing.estimated' | 'billing.actual' | 'billing.pricing' | 'billing.showPricing' | 'billing.hidePricing' | 'billing.pricePerM' | 'billing.input' | 'billing.output' | 'billing.cacheHit' | 'billing.peak' | 'billing.offPeak' | 'billing.flat' | 'billing.peakHours' | 'billing.band' | 'billing.openDashboard' | 'billing.close' | 'billing.lastUpdated' | 'billing.noData' | 'billing.todayRate' | 'billing.rateLive' | 'billing.rateBuiltin' | 'billing.balance' | 'billing.balanceUnconfigured' | 'billing.balanceUnauthorized' | 'billing.balanceUnreachable';
 export declare const NS = "usageBilling";
 export declare const zh: Record<UsageBillingKey, string>;
 export declare const en: Record<UsageBillingKey, string>;

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

@@ -12,12 +12,29 @@
  * (09:00-12:00 / 14:00-18:00 Beijing) at 2x the off-peak rate. The estimator
  * mixes both bands by a configured peak share ({@link DEFAULT_PEAK_SHARE}).
  */
+import type { LivePricing } from '../pricing-shared.ts';
 /**
  * USD → CNY rate for display. Source: China Foreign Exchange Trade System
  * mid-rate 6.7878 on 2026-08-14; rounded to 6.79. Only applies to overseas
  * USD-priced models — domestic models never pass through this rate.
+ * The node half may refresh this at boot via `/api/billing/pricing`; until a
+ * live rate arrives the built-in value stays in force.
  */
 export declare const USD_TO_CNY = 6.79;
+/**
+ * Apply the node half's live pricing snapshot. Absent fields keep the
+ * built-in catalog and rate; callers never fabricate values.
+ * @param pricing - the `/api/billing/pricing` response.
+ */
+export declare function applyLivePricing(pricing: LivePricing): void;
+/**
+ * 当前生效的 USD → CNY 汇率及其来源：live = 启动时实时拉取成功，
+ * builtin = 实时拉取失败、正在用内置默认值。
+ */
+export declare function getRateInfo(): {
+    rate: number;
+    live: boolean;
+};
 /** Default share of traffic assumed to fall in the peak band (0..1). */
 export declare const DEFAULT_PEAK_SHARE = 0.5;
 /**
@@ -98,6 +115,12 @@ export declare function resolveToken(name: string): string;
  * Estimate the CNY cost of one model's token usage, mixing the peak and
  * off-peak bands by the given peak share (flat-priced models cost the same in
  * both bands).
+ *
+ * 计费维度是「缓存命中价 × 时段价」的交叉：每个时段档内部分别按缓存命中
+ * 价（cacheHit）与未命中价（input/cacheMiss）计价，两个时段档再按
+ * peakShare 混合。时段定义以北京时间为准（如 DeepSeek V4 高峰
+ * 09:00-12:00 / 14:00-18:00）。因聚合只有按日 token 量、没有请求级时间戳，
+ * 时段只能按比例估算，而非逐请求判定。
  * @param entry - the catalog entry whose prices apply.
  * @param buckets - token usage counts.
  * @param peakShare - share of traffic in the peak band (0..1); defaults to {@link DEFAULT_PEAK_SHARE}.

package/lib/types/index.d.ts

@@ -16,6 +16,8 @@ export interface UsageBillingConfig {
     statsPath?: string;
     /** 订阅制（coding / token / agent plan）provider id 列表；默认 kimi-coding、xiaomi-token-plan-cn。 */
     subscriptionProviders?: string[];
+    /** 余额查询用的 DeepSeek 凭据引用（环境变量名）；默认 DEEPSEEK_API_KEY。 */
+    balanceApiKeyEnv?: string;
 }
 /** Required services: the web server and the persisted session log store. */
 export declare const inject: string[];

package/lib/types/pricing-fetch.d.ts

@@ -0,0 +1,17 @@
+/**
+ * One-shot live pricing refresh for the billing dashboard.
+ *
+ * Fetches the USD → CNY mid rate and the OpenRouter model price list, maps
+ * matched models onto the built-in catalog keys, and returns the combined
+ * LivePricing. Every fetch failure degrades to the built-in values: the node
+ * half caches whatever succeeded and the browser dashboard falls back to the
+ * catalog for the rest — a total outage answers `{ source: 'builtin' }`.
+ */
+import type { LivePricing } from './pricing-shared.ts';
+/**
+ * Fetch the live pricing once at boot. Both upstreams run in parallel; a
+ * failure in either degrades independently to the built-in value.
+ * @returns the live pricing snapshot (builtin when everything failed).
+ */
+export declare function fetchLivePricing(): Promise<LivePricing>;
+//# sourceMappingURL=pricing-fetch.d.ts.map

package/lib/types/pricing-shared.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Live-pricing wire types shared by the node half (which fetches and caches
+ * once at boot) and the browser half (which applies the overrides on top of
+ * the built-in catalog). An absent field means the built-in value still
+ * applies — the dashboard degrades to the catalog, never to fabricated data.
+ */
+/** One model's unit prices as reported by the router, in USD per 1M tokens. */
+export interface LivePrice {
+    /** Uncached input price per 1M tokens. */
+    input: number;
+    /** Cache-hit input price per 1M tokens (estimated as 10% of input; the router list carries no cache band). */
+    cacheHit: number;
+    /** Output price per 1M tokens. */
+    output: number;
+}
+/** Response of `/api/billing/pricing` consumed by the dashboard. */
+export interface LivePricing {
+    /** live = at least one fetch succeeded; builtin = full fallback to the catalog. */
+    source: 'live' | 'builtin';
+    /** USD → CNY mid rate (present when the rate fetch succeeded). */
+    rate?: number;
+    /** Overrides keyed by built-in catalog key (present when router matches succeeded). */
+    prices?: Record<string, LivePrice>;
+}
+/** 余额查询失败的原因，前端据此显示文案。 */
+export type BalanceError = 'unconfigured' | 'unauthorized' | 'unreachable';
+/** 一个提供方的账户余额（`/api/billing/balance` 的一行）。 */
+export interface ProviderBalance {
+    /** 提供方 id（小写，如 `deepseek`），与模型表 provider 匹配用。 */
+    provider: string;
+    /** 显示名（如 `DeepSeek`）。 */
+    displayName: string;
+    /** 余额币种（CNY / USD）。 */
+    currency?: string;
+    /** 总可用余额（含赠金与充值）。 */
+    totalBalance?: number;
+    /** 未过期赠金余额。 */
+    grantedBalance?: number;
+    /** 充值余额。 */
+    toppedUpBalance?: number;
+    /** 余额是否足以继续调用。 */
+    isAvailable?: boolean;
+    /** 未配置/鉴权失败/网络不可达等失败原因；缺省 = 查询成功。 */
+    error?: BalanceError;
+}
+/** Response of `/api/billing/balance` consumed by the dashboard. */
+export interface BalanceResponse {
+    balances: readonly ProviderBalance[];
+}
+//# sourceMappingURL=pricing-shared.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kenz1117/dsh-ui-usage-billing",
   "description": "Usage billing dashboard for DeepSeek Harness: sidebar cost metrics plus a full dashboard modal, priced from a current multi-provider catalog with real usage aggregated from session logs.",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "publishConfig": {
     "access": "public"
   },