@kenz1117/dsh-ui-usage-billing 0.1.0

package/lib/index.js

@@ -0,0 +1,698 @@
+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;
+/** Default share of traffic assumed to fall in the peak band (0..1). */
+const DEFAULT_PEAK_SHARE = .5;
+/**
+* Model keys served through a subscription plan (e.g. a coding plan or topic
+* plan) instead of metered per-token API billing. Usage through these routes
+* costs no tokens: the estimator treats them as ¥0 and the billing table
+* labels them 订阅包含. Add any model key your deployment serves through a
+* plan here; leave empty when every route is pay-as-you-go.
+*/
+const SUBSCRIPTION_PLAN_KEYS = [];
+/** Whether one stats model key is billed through a subscription plan. */
+function isSubscriptionPlan(key) {
+	return SUBSCRIPTION_PLAN_KEYS.includes(key);
+}
+/**
+* Built-in catalog of current mainstream models as of 2026-08-16, priced from
+* each provider's official price page. Domestic providers are OpenAI-API
+* compatible and publish RMB prices directly; overseas providers publish USD
+* and convert through the exchange rate at estimate time. Retired models
+* (GPT-4o family, Gemini 2.x, GLM-4.x-lite, older Qwen) are deliberately
+* absent, as are Anthropic Claude models (their native API is not
+* OpenAI-compatible, so the harness cannot drive them directly). DeepSeek
+* keys match the harness stats file so real usage prices from the catalog;
+* unknown keys fall back to `other`.
+*
+* Time-of-day billing (peak/off-peak) is now real: DeepSeek V4 officially
+* splits peak (09:00-12:00 / 14:00-18:00 Beijing) at 2x the off-peak rate
+* from 2026-08-17, and Gemini's Flex tier discounts spare-capacity traffic.
+*/
+const MODEL_CATALOG = [
+	{
+		key: "flash",
+		name: "DeepSeek V4 Flash",
+		provider: "DeepSeek",
+		colorVar: "dsw-static-blue-500",
+		price: {
+			currency: "CNY",
+			input: 3,
+			cacheHit: .1,
+			output: 9,
+			offPeak: {
+				input: 1.5,
+				cacheHit: .05,
+				output: 4.5
+			}
+		},
+		peakHours: "09:00-12:00 / 14:00-18:00"
+	},
+	{
+		key: "pro",
+		name: "DeepSeek V4 Pro",
+		provider: "DeepSeek",
+		colorVar: "dsw-static-deepseek-500",
+		price: {
+			currency: "CNY",
+			input: 9,
+			cacheHit: .3,
+			output: 27,
+			offPeak: {
+				input: 4.5,
+				cacheHit: .15,
+				output: 13.5
+			}
+		},
+		peakHours: "09:00-12:00 / 14:00-18:00"
+	},
+	{
+		key: "glm",
+		name: "GLM-5.2",
+		provider: "智谱 AI",
+		colorVar: "dsw-static-blue-600",
+		price: {
+			currency: "CNY",
+			input: 8,
+			cacheHit: 2,
+			output: 28
+		}
+	},
+	{
+		key: "glm-5.3",
+		name: "GLM-5.3",
+		provider: "智谱 AI",
+		colorVar: "dsw-static-blue-500",
+		price: {
+			currency: "CNY",
+			input: 8,
+			cacheHit: 2,
+			output: 28
+		}
+	},
+	{
+		key: "glm-4.6",
+		name: "GLM-4.6",
+		provider: "智谱 AI",
+		colorVar: "dsw-static-blue-400",
+		price: {
+			currency: "CNY",
+			input: 4,
+			cacheHit: .8,
+			output: 16
+		}
+	},
+	{
+		key: "qwen-3.8-max",
+		name: "Qwen3.8 Max",
+		provider: "阿里通义",
+		colorVar: "dsw-static-blue-600",
+		price: {
+			currency: "CNY",
+			input: 13.58,
+			cacheHit: 1.36,
+			output: 40.74
+		}
+	},
+	{
+		key: "qwen-max",
+		name: "Qwen3.7-Max",
+		provider: "阿里通义",
+		colorVar: "dsw-static-blue-300",
+		price: {
+			currency: "CNY",
+			input: 6,
+			cacheHit: .6,
+			output: 18
+		}
+	},
+	{
+		key: "qwen-plus",
+		name: "Qwen3.5-Plus",
+		provider: "阿里通义",
+		colorVar: "dsw-static-blue-500",
+		price: {
+			currency: "CNY",
+			input: .8,
+			cacheHit: .08,
+			output: 4.8
+		}
+	},
+	{
+		key: "qwen-flash",
+		name: "Qwen3.5-Flash",
+		provider: "阿里通义",
+		colorVar: "dsw-static-blue-400",
+		price: {
+			currency: "CNY",
+			input: .2,
+			cacheHit: .02,
+			output: 2
+		}
+	},
+	{
+		key: "doubao",
+		name: "Doubao Seed-2.0 Pro",
+		provider: "字节豆包",
+		colorVar: "dsw-static-red-500",
+		price: {
+			currency: "CNY",
+			input: 3.2,
+			cacheHit: .64,
+			output: 16
+		}
+	},
+	{
+		key: "doubao-mini",
+		name: "Doubao Seed-2.0 Mini",
+		provider: "字节豆包",
+		colorVar: "dsw-static-red-300",
+		price: {
+			currency: "CNY",
+			input: .2,
+			cacheHit: .02,
+			output: 2
+		}
+	},
+	{
+		key: "doubao-1.6",
+		name: "Doubao Seed-1.6",
+		provider: "字节豆包",
+		colorVar: "dsw-static-red-400",
+		price: {
+			currency: "CNY",
+			input: .8,
+			cacheHit: 0,
+			output: 8
+		}
+	},
+	{
+		key: "kimi",
+		name: "Kimi K2.7 Code",
+		provider: "月之暗面",
+		colorVar: "dsw-static-neutral-bluish-700",
+		price: {
+			currency: "CNY",
+			input: 6.5,
+			cacheHit: 1.3,
+			output: 27
+		}
+	},
+	{
+		key: "kimi-k2.7-hs",
+		name: "Kimi K2.7 Code HighSpeed",
+		provider: "月之暗面",
+		colorVar: "dsw-static-neutral-bluish-600",
+		price: {
+			currency: "CNY",
+			input: 13,
+			cacheHit: 2.6,
+			output: 54
+		}
+	},
+	{
+		key: "kimi-k2.6",
+		name: "Kimi K2.6",
+		provider: "月之暗面",
+		colorVar: "dsw-static-neutral-bluish-500",
+		price: {
+			currency: "CNY",
+			input: 6.5,
+			cacheHit: 1.1,
+			output: 27
+		}
+	},
+	{
+		key: "kimi-k3",
+		name: "Kimi K3",
+		provider: "月之暗面",
+		colorVar: "dsw-static-neutral-bluish-500",
+		price: {
+			currency: "CNY",
+			input: 20,
+			cacheHit: 2,
+			output: 100
+		}
+	},
+	{
+		key: "minimax",
+		name: "MiniMax-M3",
+		provider: "MiniMax",
+		colorVar: "dsw-static-amber-500",
+		price: {
+			currency: "CNY",
+			input: 2.1,
+			cacheHit: .42,
+			output: 8.4
+		}
+	},
+	{
+		key: "ernie",
+		name: "ERNIE-5.1",
+		provider: "百度文心",
+		colorVar: "dsw-static-blue-300",
+		price: {
+			currency: "CNY",
+			input: 4,
+			cacheHit: .4,
+			output: 18
+		}
+	},
+	{
+		key: "hunyuan",
+		name: "混元 Hy3",
+		provider: "腾讯混元",
+		colorVar: "dsw-static-amber-400",
+		price: {
+			currency: "CNY",
+			input: 1,
+			cacheHit: .25,
+			output: 4
+		}
+	},
+	{
+		key: "hunyuan-t1",
+		name: "混元 T1",
+		provider: "腾讯混元",
+		colorVar: "dsw-static-amber-300",
+		price: {
+			currency: "CNY",
+			input: 1,
+			cacheHit: .1,
+			output: 4
+		}
+	},
+	{
+		key: "yi",
+		name: "Yi-Lightning",
+		provider: "零一万物",
+		colorVar: "dsw-static-green-500",
+		price: {
+			currency: "CNY",
+			input: .99,
+			cacheHit: .1,
+			output: .99
+		}
+	},
+	{
+		key: "step",
+		name: "Step 3.7 Flash",
+		provider: "阶跃星辰",
+		colorVar: "dsw-static-neutral-bluish-400",
+		price: {
+			currency: "CNY",
+			input: 1.35,
+			cacheHit: .27,
+			output: 8.1
+		}
+	},
+	{
+		key: "spark",
+		name: "Spark 4.0 Ultra",
+		provider: "科大讯飞",
+		colorVar: "dsw-static-green-400",
+		price: {
+			currency: "CNY",
+			input: 5,
+			cacheHit: .5,
+			output: 10
+		}
+	},
+	{
+		key: "sensenova",
+		name: "SenseNova 6.5",
+		provider: "商汤",
+		colorVar: "dsw-static-red-400",
+		price: {
+			currency: "CNY",
+			input: 4.5,
+			cacheHit: .45,
+			output: 9
+		}
+	},
+	{
+		key: "baichuan",
+		name: "Baichuan M3-Plus",
+		provider: "百川智能",
+		colorVar: "dsw-static-neutral-bluish-500",
+		price: {
+			currency: "CNY",
+			input: 5,
+			cacheHit: .5,
+			output: 9
+		}
+	},
+	{
+		key: "gpt-5.6-sol",
+		name: "GPT-5.6 Sol",
+		provider: "OpenAI",
+		colorVar: "dsw-static-green-500",
+		price: {
+			currency: "USD",
+			input: 5,
+			cacheHit: .5,
+			output: 30
+		}
+	},
+	{
+		key: "gpt-5.6-terra",
+		name: "GPT-5.6 Terra",
+		provider: "OpenAI",
+		colorVar: "dsw-static-green-400",
+		price: {
+			currency: "USD",
+			input: 2,
+			cacheHit: .2,
+			output: 12
+		}
+	},
+	{
+		key: "gpt-5.6-luna",
+		name: "GPT-5.6 Luna",
+		provider: "OpenAI",
+		colorVar: "dsw-static-green-500",
+		price: {
+			currency: "USD",
+			input: .2,
+			cacheHit: .02,
+			output: 1.2
+		}
+	},
+	{
+		key: "gemini-pro",
+		name: "Gemini 3.1 Pro",
+		provider: "Google",
+		colorVar: "dsw-static-blue-600",
+		price: {
+			currency: "USD",
+			input: 2,
+			cacheHit: .2,
+			output: 12,
+			offPeak: {
+				input: 1,
+				cacheHit: .1,
+				output: 6
+			}
+		},
+		peakHours: "Standard / Flex"
+	},
+	{
+		key: "gemini-flash",
+		name: "Gemini 3.6 Flash",
+		provider: "Google",
+		colorVar: "dsw-static-blue-400",
+		price: {
+			currency: "USD",
+			input: 1.5,
+			cacheHit: .15,
+			output: 7.5,
+			offPeak: {
+				input: .75,
+				cacheHit: .075,
+				output: 3.75
+			}
+		},
+		peakHours: "Standard / Flex"
+	},
+	{
+		key: "grok",
+		name: "Grok 4.6",
+		provider: "xAI",
+		colorVar: "dsw-static-neutral-bluish-700",
+		price: {
+			currency: "USD",
+			input: 2,
+			cacheHit: .5,
+			output: 6
+		}
+	},
+	{
+		key: "grok-4.3",
+		name: "Grok 4.3",
+		provider: "xAI",
+		colorVar: "dsw-static-neutral-bluish-500",
+		price: {
+			currency: "USD",
+			input: 1.25,
+			cacheHit: .2,
+			output: 2.5
+		}
+	},
+	{
+		key: "llama",
+		name: "Llama 4 Maverick",
+		provider: "Meta",
+		colorVar: "dsw-static-red-500",
+		price: {
+			currency: "USD",
+			input: .2,
+			cacheHit: .05,
+			output: .6
+		}
+	},
+	{
+		key: "llama-scout",
+		name: "Llama 4 Scout",
+		provider: "Meta",
+		colorVar: "dsw-static-red-400",
+		price: {
+			currency: "USD",
+			input: .1,
+			cacheHit: .025,
+			output: .3
+		}
+	},
+	{
+		key: "other",
+		name: "其他模型",
+		provider: "Custom",
+		colorVar: "dsw-static-neutral-bluish-500",
+		price: {
+			currency: "CNY",
+			input: .5,
+			cacheHit: .25,
+			cacheMiss: .5,
+			output: 1.5
+		}
+	}
+];
+/** Lookup a model by its stats key; falls back to the generic `other` entry. */
+function modelOf(key) {
+	return MODEL_CATALOG.find((entry) => entry.key === key) ?? MODEL_CATALOG[MODEL_CATALOG.length - 1];
+}
+/**
+* Price one band's token usage in CNY. The stats `input` field is the TOTAL
+* prompt tokens (cacheHit + cacheMiss), so billing splits it: the cache-hit
+* share prices at the hit rate and the remaining share at the miss rate.
+* Providers that report only disjoint buckets carry `cacheMiss` explicitly;
+* otherwise the miss share is derived as `input - cacheHit`. Only USD-priced
+* bands go through the exchange rate.
+*/
+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;
+}
+/**
+* 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).
+* @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}.
+* @returns the estimated cost in CNY.
+*/
+function computeCost(entry, buckets, peakShare = DEFAULT_PEAK_SHARE) {
+	if (isSubscriptionPlan(entry.key)) return 0;
+	const peak = priceBandCost(entry.price, buckets, entry.price.currency);
+	const off = entry.price.offPeak === void 0 ? peak : priceBandCost(entry.price.offPeak, buckets, entry.price.currency);
+	return peak * peakShare + off * (1 - peakShare);
+}
+//#endregion
+//#region lib/types/aggregate.js
+/**
+* Real-usage aggregation: folds every persisted session log into the
+* usage-stats document the dashboard renders.
+*
+* Each LLM call is attributed to the model of the `request/header` event that
+* precedes its `assistant/message` usage event. Costs are estimated with the
+* shared billing catalog (`pricing.ts`, in CNY), so only models the catalog
+* prices incur a cost — subscription-plan routes and unknown models price
+* zero while their tokens still count. Pure functions only: the persistence
+* handle is injected, so the fold is unit-testable without a host.
+*/
+/**
+* Real provider model ids map to their billing-catalog keys. Unknown ids stay
+* as-is and price zero (they are not in the catalog; subscription-plan routes
+* like kimi-coding / token plans fall here and therefore cost nothing).
+*/
+const MODEL_KEY_ALIASES = {
+	"deepseek-v4-flash": "flash",
+	"deepseek-v4-pro": "pro",
+	"glm-5.2": "glm",
+	"qwen3.8-max": "qwen-3.8-max",
+	"qwen3.7-max": "qwen-max",
+	"qwen-max": "qwen-max",
+	"hunyuan-t1": "hunyuan-t1",
+	"step-3.7-flash": "step",
+	"seed-2.0-mini": "doubao-mini"
+};
+/**
+* 走订阅套餐（coding / token / agent plan）的 provider id：这些通道的调用
+* 按套餐计费，不再按 token 计费，因此即使模型 id 与计费表撞名也一律豁免。
+* 部署可在 plugin config 的 `subscriptionProviders` 中覆盖。
+*/
+const DEFAULT_SUBSCRIPTION_PROVIDERS = ["kimi-coding", "xiaomi-token-plan-cn"];
+/** Zeroed usage accumulator. */
+function emptyUsage() {
+	return {
+		calls: 0,
+		input: 0,
+		output: 0,
+		cacheHit: 0,
+		cacheMiss: 0,
+		cost: 0
+	};
+}
+/**
+* Fold one token usage event into an accumulator and re-price its cost.
+* The stats `input` is the TOTAL prompt tokens (cacheHit + cacheMiss), so the
+* miss bucket is uncached input plus cache writes.
+* @param acc - the accumulator to mutate.
+* @param usage - the provider-reported usage of one call.
+* @param key - the billing-catalog key this call belongs to.
+* @param subscription - whether the call went through a subscription plan; such calls never cost money.
+*/
+function foldUsage(acc, usage, key, subscription) {
+	const cacheHit = usage.cacheReadTokens ?? 0;
+	const cacheMiss = usage.inputTokens + (usage.cacheWriteTokens ?? 0);
+	acc.calls += 1;
+	acc.input += usage.inputTokens + cacheHit + (usage.cacheWriteTokens ?? 0);
+	acc.output += usage.outputTokens;
+	acc.cacheHit += cacheHit;
+	acc.cacheMiss += cacheMiss;
+	acc.cost = !subscription && MODEL_CATALOG.some((entry) => entry.key === key) ? computeCost(modelOf(key), {
+		input: acc.input,
+		cacheHit: acc.cacheHit,
+		cacheMiss: acc.cacheMiss,
+		output: acc.output
+	}) : 0;
+}
+/** Local-time date stamp (the host runs in the user's timezone). */
+function dayStamp(time) {
+	const date = new Date(time);
+	const pad = (n) => String(n).padStart(2, "0");
+	return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+/**
+* Aggregate real usage from every persisted session log.
+* @param persistence - the session persistence service.
+* @param options - aggregation tuning (e.g. subscription-plan providers).
+* @returns the usage-stats document (same shape the dashboard expects).
+*/
+async function aggregateUsage(persistence, options = {}) {
+	const subscriptionProviders = new Set(options.subscriptionProviders ?? DEFAULT_SUBSCRIPTION_PROVIDERS);
+	const total = emptyUsage();
+	const byModel = /* @__PURE__ */ new Map();
+	const byDay = /* @__PURE__ */ new Map();
+	for (const meta of await persistence.list()) {
+		const { events } = await persistence.readFrom(meta.id, 0);
+		let key = "other";
+		let subscription = false;
+		for (const event of events) {
+			if (event.type === "request/header") {
+				const { model, provider } = event.data.header.config;
+				key = MODEL_KEY_ALIASES[model] ?? model;
+				subscription = subscriptionProviders.has(provider);
+				continue;
+			}
+			if (event.type !== "assistant/message" || event.data.usage === void 0) continue;
+			const modelKey = key;
+			const day = dayStamp(event.time);
+			foldUsage(total, event.data.usage, modelKey, subscription);
+			foldUsage(byModel.get(modelKey) ?? byModel.set(modelKey, emptyUsage()).get(modelKey), event.data.usage, modelKey, subscription);
+			foldUsage(byDay.get(day) ?? byDay.set(day, emptyUsage()).get(day), event.data.usage, modelKey, subscription);
+		}
+	}
+	const toRecord = (map) => Object.fromEntries(map);
+	return {
+		version: 1,
+		updatedAt: Date.now(),
+		source: "session-logs",
+		total,
+		byModel: toRecord(byModel),
+		byDay: toRecord(byDay)
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Usage billing surface plugin, node half.
+*
+* Serves `/api/billing/usage-stats`: real usage aggregated from every
+* persisted session log (see `aggregate.ts`) — the browser dashboard reads it
+* instead of showing an empty snapshot. When `sessionPersistence` is
+* unavailable (or aggregation fails), the configured `statsPath` /
+* `DSH_USAGE_STATS` / conventional JSON file is served as a fallback, and a
+* missing file answers `{ error }` so the dashboard shows zeros, never
+* fabricated samples.
+*/
+/** Required services: the web server and the persisted session log store. */
+const inject = ["webServer", "sessionPersistence"];
+/**
+* Host plugin body: serve real aggregated usage to the browser dashboard.
+* @param ctx - host context carrying webServer and sessionPersistence.
+* @param config - optional statsPath override.
+*/
+function apply(ctx, config = {}) {
+	const cwd = process.cwd();
+	const candidates = [
+		config.statsPath,
+		process.env.DSH_USAGE_STATS,
+		join(cwd, ".dsh-usage-stats.json"),
+		join(homedir(), ".dsh/.dsh-usage-stats.json")
+	].filter((path) => typeof path === "string" && path.length > 0);
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/api/billing/usage-stats",
+		handler: async (_req, res) => {
+			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+			try {
+				res.end(JSON.stringify(await aggregateUsage(ctx.sessionPersistence, { ...config.subscriptionProviders === void 0 ? {} : { subscriptionProviders: config.subscriptionProviders } })));
+				return;
+			} catch {}
+			for (const candidate of candidates) try {
+				const text = await readFile(candidate, "utf8");
+				JSON.parse(text);
+				res.end(text);
+				return;
+			} catch {}
+			res.end(JSON.stringify({ error: "usage stats unavailable" }));
+		}
+	}), "usage-billing: usage-stats route");
+}
+//#endregion
+export { apply, inject };

package/lib/invariant.js

@@ -0,0 +1,15 @@
+//#region lib/types/invariant.js
+/** Package invariant companion for `@kenz1117/dsh-ui-usage-billing`. */
+const PACKAGE_NAME = "@kenz1117/dsh-ui-usage-billing";
+const name = "usage-billing-invariant";
+const inject = ["invariants"];
+/** No runtime invariant: pure UI surface plugin with no lifecycle dependencies. */
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Host context carrying the invariant registry.
+* @returns the registration disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };