@kenz1117/dsh-ui-usage-billing 1.0.2 → 1.0.3

package/lib/index.js

@@ -326,6 +326,23 @@ const MODEL_CATALOG = [
 			output: 28
 		}
 	},
+	{
+		key: "glm-5.3-flash",
+		name: "GLM-5.3-Flash",
+		provider: "智谱 AI",
+		colorVar: "dsw-static-blue-300",
+		price: {
+			currency: "CNY",
+			input: .8,
+			cacheHit: .23,
+			output: 2.8
+		},
+		promo: {
+			factor: .5,
+			endsAtMs: Date.UTC(2026, 8, 8, 16, 0, 0),
+			note: "限时 5 折"
+		}
+	},
 	{
 		key: "glm-4.6",
 		name: "GLM-4.6",
@@ -406,10 +423,66 @@ const MODEL_CATALOG = [
 		colorVar: "dsw-static-blue-600",
 		price: {
 			currency: "CNY",
-			input: 13.58,
-			cacheHit: 1.36,
-			output: 40.74
-		}
+			input: 12,
+			cacheHit: 1.5,
+			output: 36
+		},
+		extraRows: [
+			{
+				label: "显式缓存创建",
+				input: 15
+			},
+			{
+				label: "显式缓存命中",
+				input: 1
+			},
+			{
+				label: "Batch File",
+				input: 6,
+				output: 18,
+				note: "长期半价"
+			},
+			{
+				label: "Batch Chat",
+				input: 12,
+				output: 36,
+				note: "与标准价一致"
+			}
+		]
+	},
+	{
+		key: "qwen-3.8-flash",
+		name: "Qwen3.8 Flash",
+		provider: "阿里通义",
+		colorVar: "dsw-static-blue-400",
+		price: {
+			currency: "CNY",
+			input: 1,
+			cacheHit: .1,
+			output: 3
+		},
+		extraRows: [
+			{
+				label: "显式缓存创建",
+				input: 1.25
+			},
+			{
+				label: "显式缓存命中",
+				input: .1
+			},
+			{
+				label: "Batch File",
+				input: .5,
+				output: 1.5,
+				note: "长期半价"
+			},
+			{
+				label: "Batch Chat",
+				input: 1,
+				output: 3,
+				note: "与标准价一致"
+			}
+		]
 	},
 	{
 		key: "qwen-max",
@@ -418,10 +491,36 @@ const MODEL_CATALOG = [
 		colorVar: "dsw-static-blue-300",
 		price: {
 			currency: "CNY",
-			input: 6,
-			cacheHit: .6,
-			output: 18
-		}
+			input: 12,
+			cacheHit: 1.2,
+			output: 36
+		},
+		promo: {
+			factor: .5,
+			note: "限时 5 折"
+		},
+		extraRows: [
+			{
+				label: "显式缓存创建",
+				input: 15
+			},
+			{
+				label: "显式缓存命中",
+				input: 1.2
+			},
+			{
+				label: "Batch File",
+				input: 6,
+				output: 18,
+				note: "长期半价"
+			},
+			{
+				label: "Batch Chat",
+				input: 12,
+				output: 36,
+				note: "与标准价一致"
+			}
+		]
 	},
 	{
 		key: "qwen-plus",
@@ -433,7 +532,29 @@ const MODEL_CATALOG = [
 			input: .8,
 			cacheHit: .08,
 			output: 4.8
-		}
+		},
+		extraRows: [
+			{
+				label: "显式缓存创建",
+				input: 1
+			},
+			{
+				label: "显式缓存命中",
+				input: .08
+			},
+			{
+				label: "Batch File",
+				input: .4,
+				output: 2.4,
+				note: "长期半价"
+			},
+			{
+				label: "Batch Chat",
+				input: .8,
+				output: 4.8,
+				note: "与标准价一致"
+			}
+		]
 	},
 	{
 		key: "qwen-flash",
@@ -445,7 +566,14 @@ const MODEL_CATALOG = [
 			input: .2,
 			cacheHit: .02,
 			output: 2
-		}
+		},
+		extraRows: [{
+			label: "显式缓存创建",
+			input: .25
+		}, {
+			label: "显式缓存命中",
+			input: .02
+		}]
 	},
 	{
 		key: "doubao",
@@ -1027,7 +1155,14 @@ const MODEL_CATALOG = [
 			input: 9,
 			cacheHit: .9,
 			output: 54
-		}
+		},
+		extraRows: [{
+			label: "显式缓存创建",
+			input: 11.25
+		}, {
+			label: "显式缓存命中",
+			input: .9
+		}]
 	},
 	{
 		key: "qwen3-coder-plus",
@@ -1039,7 +1174,14 @@ const MODEL_CATALOG = [
 			input: 4,
 			cacheHit: .8,
 			output: 16
-		}
+		},
+		extraRows: [{
+			label: "显式缓存创建",
+			input: 5
+		}, {
+			label: "显式缓存命中",
+			input: .4
+		}]
 	},
 	{
 		key: "qwen3-coder",
@@ -1198,6 +1340,7 @@ const MODEL_KEY_ALIASES = {
 	"glm-4.7": "glm-4.7",
 	"glm-5-turbo": "glm-5-turbo",
 	"glm-5.1": "glm-5.1",
+	"glm-5.3-flash": "glm-5.3-flash",
 	"glm-5v-turbo": "glm-5v-turbo",
 	"glm-5v.1": "glm-5v-turbo",
 	"claude-opus-4-6": "claude-opus-4-6",
@@ -1235,6 +1378,7 @@ const MODEL_KEY_ALIASES = {
 	"doubao-seed-2.1-turbo": "doubao-seed-2.1-turbo",
 	"doubao-seed-2-1-turbo": "doubao-seed-2.1-turbo",
 	"qwen3.8-max": "qwen-3.8-max",
+	"qwen3.8-flash": "qwen-3.8-flash",
 	"qwen3.7-max": "qwen-max",
 	"qwen3.6-max": "qwen3.6-max",
 	"qwen3.6-max-preview": "qwen3.6-max",
@@ -1379,6 +1523,42 @@ function isPriced(key) {
 	return FALLBACK_RATES.some((rate) => rate.key.toLowerCase() === resolved.toLowerCase());
 }
 /**
+* 促销在 nowMs 是否生效：factor 必须落在 (0,1) 区间，截止时刻及之后视为过期；
+* endsAtMs 缺省表示长期活动，在 factor 合法期间持续生效。
+* 导出供测试：纯函数。
+* @param promo - 待判定的促销窗口。
+* @param nowMs - 判定时刻（epoch ms）。
+*/
+function isPromoActive(promo, nowMs) {
+	const expired = promo.endsAtMs !== void 0 && nowMs >= promo.endsAtMs;
+	return Number.isFinite(nowMs) && !expired && promo.factor > 0 && promo.factor < 1;
+}
+/**
+* 把限时促销折入条目单价：生效期内返回 price 主档与 offPeak 全部乘 factor 的
+* 副本，其余字段原样保留；不在促销期（过期/未开始/factor 非法）原样返回。
+* 幂等由调用方保证——计价与费率表显示各自只折一次，勿对已折价副本重复应用。
+* @param entry - 目录条目（price 保持刊例价口径）。
+* @param nowMs - 判定时刻（epoch ms）。
+*/
+function applyPromo(entry, nowMs) {
+	const { promo } = entry;
+	if (promo === void 0 || !isPromoActive(promo, nowMs)) return entry;
+	const scaled = (band) => ({
+		input: band.input * promo.factor,
+		cacheHit: band.cacheHit * promo.factor,
+		...band.cacheMiss !== void 0 ? { cacheMiss: band.cacheMiss * promo.factor } : {},
+		output: band.output * promo.factor
+	});
+	return {
+		...entry,
+		price: {
+			...scaled(entry.price),
+			currency: entry.price.currency,
+			...entry.price.offPeak !== void 0 ? { offPeak: scaled(entry.price.offPeak) } : {}
+		}
+	};
+}
+/**
 * 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.
@@ -1407,15 +1587,17 @@ function priceBandCost(band, buckets, currency) {
 * @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) {
-	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);
+function computeCost(entry, buckets, peakShare = DEFAULT_PEAK_SHARE, nowMs = Date.now()) {
+	const priced = applyPromo(entry, nowMs);
+	const peak = priceBandCost(priced.price, buckets, priced.price.currency);
+	const off = priced.price.offPeak === void 0 ? peak : priceBandCost(priced.price.offPeak, buckets, priced.price.currency);
 	return peak * peakShare + off * (1 - peakShare);
 }
 /**
 * 按调用时刻精确判定高峰/空闲档并计价（P0-1：替代固定比例混合）。时刻未知
 * （null/NaN，理论不发生在真实事件流）时回退 {@link DEFAULT_PEAK_SHARE} 混合，
-* 保持旧语义不低估。平档模型（无 offPeak）两个时段同价。
+* 保持旧语义不低估。平档模型（无 offPeak）两个时段同价。限时促销与峰谷档
+* 同口径：按事件时刻判定该笔流量当时享受的单价。
 * @param entry - the catalog entry whose prices apply.
 * @param buckets - token usage counts.
 * @param timeMs - the call's wall-clock time (epoch ms); null falls back to the peak-share mix.
@@ -1423,9 +1605,10 @@ function computeCost(entry, buckets, peakShare = DEFAULT_PEAK_SHARE) {
 * @returns the estimated cost in CNY（USD 计价模型已按当前汇率折算）。
 */
 function computeCostAt(entry, buckets, timeMs, peakShare = DEFAULT_PEAK_SHARE) {
-	if (entry.price.offPeak === void 0) return priceBandCost(entry.price, buckets, entry.price.currency);
 	if (timeMs === null || timeMs === void 0 || !Number.isFinite(timeMs)) return computeCost(entry, buckets, peakShare);
-	return priceBandCost(tierAt(timeMs) === "peak" ? entry.price : entry.price.offPeak, buckets, entry.price.currency);
+	const priced = applyPromo(entry, timeMs);
+	if (priced.price.offPeak === void 0) return priceBandCost(priced.price, buckets, priced.price.currency);
+	return priceBandCost(tierAt(timeMs) === "peak" ? priced.price : priced.price.offPeak, buckets, priced.price.currency);
 }
 /**
 * Format an amount with adaptive precision and the given currency symbol.
@@ -4407,6 +4590,7 @@ const UsageBillingSettingsSchema = z.object({ [ENABLE_USAGE_STATS_TOOL_FIELD]: z
 const PRICING_REFRESH_INTERVAL_MS = 360 * 60 * 1e3;
 /** 订阅套餐额度缓存时长（毫秒）：上游配额 API 低频变化，5 分钟足够。 */
 const SUBSCRIPTION_CACHE_MS = 300 * 1e3;
+const BALANCE_CACHE_MS = 300 * 1e3;
 /** DeepSeek 余额查询的默认凭据引用（与 llm-deepseek 的默认引用一致）。 */
 const DEFAULT_BALANCE_API_KEY_ENV = "DEEPSEEK_API_KEY";
 /**
@@ -4890,6 +5074,10 @@ function apply(ctx, config = {}) {
 			res.end(JSON.stringify(live));
 		}
 	}), "usage-billing: pricing route");
+	let balanceCache = {
+		at: 0,
+		doc: { balances: [] }
+	};
 	ctx.effect(() => ctx.webServer.register({
 		kind: "exact",
 		path: "/api/billing/balance",
@@ -4903,39 +5091,53 @@ function apply(ctx, config = {}) {
 				...providers["deepseek"],
 				apiKeyEnv: config.balanceApiKeyEnv ?? DEFAULT_BALANCE_API_KEY_ENV
 			};
-			const balances = await queryBalances(ctx, providers);
-			const custom = await queryCustomBalances(ctx, config.customBalances ?? []);
-			const declared = await queryDeclaredEndpoints(ctx, piProviders, config.declaredEndpoints ?? []);
-			for (const row of [
-				...balances,
-				...custom,
-				...declared
-			]) if (row.error === "unauthorized") warnAuthOnce("balance", row.provider, row.displayName);
-			const official = balances.find((row) => row.provider === "deepseek");
-			let reconcile;
-			if (official !== void 0 && official.totalBalance !== void 0) {
-				const now = Date.now();
-				const today = dayStamp(now);
-				let todayOfficialCost = 0;
-				try {
-					todayOfficialCost = (await aggregator.aggregate()).byDay[today]?.officialCost ?? 0;
-				} catch {}
-				const result = reconcileBalanceDelta(reconcileRef, official, todayOfficialCost, today, now);
-				reconcileRef = result.ref;
-				if (result.event !== null && result.event.kind !== "flat") reconcile = {
-					...result.event,
-					provider: official.displayName
-				};
-				if (result.ref !== null) persistReconcileRef();
+			if (Date.now() - balanceCache.at < BALANCE_CACHE_MS) {
+				res.end(JSON.stringify(balanceCache.doc));
+				return;
 			}
-			res.end(JSON.stringify({
-				balances: [
+			try {
+				const balances = await queryBalances(ctx, providers);
+				const custom = await queryCustomBalances(ctx, config.customBalances ?? []);
+				const declared = await queryDeclaredEndpoints(ctx, piProviders, config.declaredEndpoints ?? []);
+				for (const row of [
 					...balances,
 					...custom,
 					...declared
-				],
-				...reconcile === void 0 ? {} : { reconcile }
-			}));
+				]) if (row.error === "unauthorized") warnAuthOnce("balance", row.provider, row.displayName);
+				const official = balances.find((row) => row.provider === "deepseek");
+				let reconcile;
+				if (official !== void 0 && official.totalBalance !== void 0) {
+					const now = Date.now();
+					const today = dayStamp(now);
+					let todayOfficialCost = 0;
+					try {
+						todayOfficialCost = (await aggregator.aggregate()).byDay[today]?.officialCost ?? 0;
+					} catch {}
+					const result = reconcileBalanceDelta(reconcileRef, official, todayOfficialCost, today, now);
+					reconcileRef = result.ref;
+					if (result.event !== null && result.event.kind !== "flat") reconcile = {
+						...result.event,
+						provider: official.displayName
+					};
+					if (result.ref !== null) persistReconcileRef();
+				}
+				const doc = {
+					balances: [
+						...balances,
+						...custom,
+						...declared
+					],
+					...reconcile === void 0 ? {} : { reconcile }
+				};
+				balanceCache = {
+					at: Date.now(),
+					doc
+				};
+				res.end(JSON.stringify(doc));
+			} catch (error) {
+				console.warn("[usage-billing] refreshBalances failed; serving cached balances:", error);
+				res.end(JSON.stringify(balanceCache.doc));
+			}
 		}
 	}), "usage-billing: balance route");
 	ctx.effect(() => ctx.webServer.register({

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.monthProjected' | 'billing.liveTurn' | 'billing.liveSession' | 'billing.totalCost' | 'billing.calls' | 'billing.cacheHitRate' | 'billing.tokens' | 'billing.inputTokens' | 'billing.outputTokens' | 'billing.avgCost' | 'billing.trend' | 'billing.trend7d' | 'billing.trend30d' | 'billing.trendMetric' | 'billing.trendMetricCost' | 'billing.trendMetricTokens' | 'billing.trendEmpty' | 'billing.budget' | 'billing.budgetAmount' | 'billing.budgetSummary' | 'billing.sessions' | 'billing.sessionTitle' | 'billing.project' | 'billing.lastActive' | 'billing.sessionOverflow' | 'billing.budgetTierBody' | 'billing.models' | 'billing.providerBilling' | '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.footer' | 'billing.footerCredit' | 'billing.lastUpdated' | 'billing.noData' | 'billing.todayRate' | 'billing.rateLive' | 'billing.rateBuiltin' | 'billing.pricingTip' | 'billing.pricingUnit' | 'billing.pricingNotes' | 'billing.ubPeak' | 'billing.ubOff' | 'billing.peakBand' | 'billing.pricingSource' | 'billing.noteCache' | 'billing.noteBand' | 'billing.noteSource' | 'billing.balance' | 'billing.balanceUnconfigured' | 'billing.balanceUnauthorized' | 'billing.balanceUnreachable' | 'billing.uncatalogued' | 'billing.estimatedPricing' | 'billing.balanceDays' | 'billing.balanceLowBody' | 'billing.reconcileDrift' | 'billing.reconcileDismiss' | 'billing.subscriptions' | 'billing.subscriptionNotConfigured' | 'billing.subscriptionUnauthorized' | 'billing.subscriptionUnavailable' | 'billing.subscriptionInvalid' | 'billing.subscriptionRateLimited' | 'billing.subscriptionSession' | 'billing.subscriptionWeekly' | 'billing.subscriptionMonthly' | 'billing.subscriptionBilling' | 'billing.subscriptionRemaining' | 'billing.subscriptionExhausted' | 'billing.subscriptionReset' | 'billing.subscriptionNoApi' | 'billing.floatWindow' | 'billing.floatModeCombined' | 'billing.floatModeSubscription' | 'billing.floatMode' | 'billing.floatTargets' | 'billing.floatWindowHint' | 'billing.floatNoTargets' | 'billing.floatNoTargetsHint' | 'billing.floatPrev' | 'billing.floatNext' | 'billing.subscriptionsStale' | 'billing.heatmapLess' | 'billing.heatmapMore' | 'billing.currency' | 'billing.currencyCny' | 'billing.currencyUsd' | 'billing.heatmap' | 'billing.rounds' | 'billing.roundsHint' | 'billing.anomaly' | 'billing.workspaces' | 'billing.workspacesHint' | 'billing.plan' | 'billing.remaining' | 'billing.unknownModel' | 'billing.model' | 'billing.thModel' | 'billing.thInputMiss' | 'billing.thInputHit' | 'billing.currentRound' | 'billing.costAbbr' | 'billing.tabOverview' | 'billing.tabTrends' | 'billing.tabProviders' | 'billing.tabDetails' | 'billing.tabPricing' | 'billing.tabSettings' | 'billing.settingsHead' | 'billing.settingsHint' | 'billing.budgetHint' | 'billing.peakAlertHint' | 'billing.peakAlertDescPeak' | 'billing.peakAlertDescOff' | 'billing.export' | 'billing.exportCsvDay' | 'billing.exportCsvSession' | 'billing.exportJson' | 'billing.peakShare' | 'billing.peakShareHint' | 'billing.weekCost' | 'billing.roleCost' | 'billing.roleUser' | 'billing.roleAssistant' | 'billing.roleTool' | 'billing.roleHint' | 'billing.tierPeak' | 'billing.tierOff' | 'billing.tierToPeak' | 'billing.tierToOff' | 'billing.tierAlertEnterPeak' | 'billing.tierAlertEnterOff' | 'billing.peakAlertTitlePeak' | 'billing.peakAlertTitleOff' | 'billing.peakAlert' | 'billing.peakAlertLeadMin' | 'billing.peakAlertPos' | 'billing.peakAlertMode' | 'billing.peakAlertPosCorner' | 'billing.peakAlertPosCenter' | 'billing.peakAlertModePeak' | 'billing.peakAlertModeOff' | 'billing.peakAlertModeBoth' | 'billing.peakAlertWebNotify' | 'billing.peakAlertPreview' | 'billing.planTypeCode' | 'billing.planTypeToken' | 'billing.subscriptionFeePerMonth' | 'billing.triggerToday' | 'billing.triggerMonth' | 'billing.subscriptionIncluded' | 'billing.free' | 'billing.official' | 'billing.thirdParty' | 'billing.officialCost' | 'billing.thirdPartyCost' | 'billing.perfSamples' | 'billing.perfTtft' | 'billing.perfP50' | 'billing.perfP90' | 'billing.perfTps' | 'billing.perfLatency' | 'billing.perfEstimated' | 'billing.perfEmpty' | 'billing.perfTpsUnit' | 'billing.perfTitle' | 'billing.perfHint' | 'billing.heatmapYear' | 'billing.heatmapMonth' | 'billing.activeDays' | 'billing.streakDays' | 'billing.subscriptionAutoDetect' | 'billing.pluginInfo' | 'billing.pluginName' | 'billing.pluginDescription' | 'billing.pluginVersion' | 'billing.pluginAuthor' | 'billing.pluginRepository' | 'billing.pluginNpm' | 'billing.pluginLicense' | 'billing.tabToken' | 'billing.tokenExport' | 'billing.tokenExportCsv' | 'billing.tokenCacheHitRate' | 'billing.tokenReasoningShare' | 'billing.tokenReasoningShort' | 'billing.tokenIo' | 'billing.tokenPeak' | 'billing.tokenDaily' | 'billing.tokenByModel' | 'billing.tokenMiss' | 'billing.tokenHit' | 'billing.tokenOutput' | 'billing.tokenTotal' | 'billing.tokenShare' | 'billing.usageStatsTool' | 'billing.usageStatsToolHint' | 'billing.balanceGranted' | 'billing.balanceTopped' | 'billing.balanceDaily' | 'billing.balanceDaysLong' | 'billing.balanceDaysUnit' | 'billing.popTodayModel' | 'billing.popNoConsumption' | 'billing.popQuotaAlert' | 'billing.popRiskNone' | 'billing.popTitle' | 'billing.popDirectLead' | 'billing.popSubLead' | 'billing.popBalanceNormal' | 'billing.popBalanceLow' | 'billing.popQuotaNormal' | 'billing.popQuotaLow' | 'billing.alertBalanceLow' | 'billing.alertQuotaLow' | 'billing.unpricedHint' | 'billing.exportCsvSite' | 'billing.panelRelay' | 'billing.relaySite' | 'billing.relayDirect' | 'billing.relayUnknown' | 'billing.panelRelayQuota' | 'billing.relayBalance' | 'billing.relayNoQuota' | 'billing.relayWindowUsed' | 'billing.relayKindNewApi' | 'billing.relayKindSub2Api' | 'billing.relayKindUnknown' | 'billing.relayCalls';
+export type UsageBillingKey = 'billing.title' | 'billing.subtitle' | 'billing.cost' | 'billing.todayCost' | 'billing.monthCost' | 'billing.yearCost' | 'billing.monthProjected' | 'billing.liveTurn' | 'billing.liveSession' | 'billing.totalCost' | 'billing.calls' | 'billing.cacheHitRate' | 'billing.tokens' | 'billing.inputTokens' | 'billing.outputTokens' | 'billing.avgCost' | 'billing.trend' | 'billing.trend7d' | 'billing.trend30d' | 'billing.trendMetric' | 'billing.trendMetricCost' | 'billing.trendMetricTokens' | 'billing.trendEmpty' | 'billing.budget' | 'billing.budgetAmount' | 'billing.budgetSummary' | 'billing.sessions' | 'billing.sessionTitle' | 'billing.project' | 'billing.lastActive' | 'billing.sessionOverflow' | 'billing.budgetTierBody' | 'billing.models' | 'billing.providerBilling' | '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.footer' | 'billing.footerCredit' | 'billing.lastUpdated' | 'billing.noData' | 'billing.todayRate' | 'billing.rateLive' | 'billing.rateBuiltin' | 'billing.promoBadge' | 'billing.promoUntil' | 'billing.promoOpenEnded' | 'billing.pricingTip' | 'billing.pricingUnit' | 'billing.pricingNotes' | 'billing.ubPeak' | 'billing.ubOff' | 'billing.peakBand' | 'billing.pricingSource' | 'billing.noteCache' | 'billing.noteBand' | 'billing.noteSource' | 'billing.balance' | 'billing.balanceUnconfigured' | 'billing.balanceUnauthorized' | 'billing.balanceUnreachable' | 'billing.uncatalogued' | 'billing.estimatedPricing' | 'billing.balanceDays' | 'billing.balanceLowBody' | 'billing.reconcileDrift' | 'billing.reconcileDismiss' | 'billing.subscriptions' | 'billing.subscriptionNotConfigured' | 'billing.subscriptionUnauthorized' | 'billing.subscriptionUnavailable' | 'billing.subscriptionInvalid' | 'billing.subscriptionRateLimited' | 'billing.subscriptionSession' | 'billing.subscriptionWeekly' | 'billing.subscriptionMonthly' | 'billing.subscriptionBilling' | 'billing.subscriptionRemaining' | 'billing.subscriptionExhausted' | 'billing.subscriptionReset' | 'billing.subscriptionNoApi' | 'billing.floatWindow' | 'billing.floatModeCombined' | 'billing.floatModeSubscription' | 'billing.floatMode' | 'billing.floatTargets' | 'billing.floatWindowHint' | 'billing.floatNoTargets' | 'billing.floatNoTargetsHint' | 'billing.floatPrev' | 'billing.floatNext' | 'billing.subscriptionsStale' | 'billing.heatmapLess' | 'billing.heatmapMore' | 'billing.currency' | 'billing.currencyCny' | 'billing.currencyUsd' | 'billing.heatmap' | 'billing.rounds' | 'billing.roundsHint' | 'billing.anomaly' | 'billing.workspaces' | 'billing.workspacesHint' | 'billing.plan' | 'billing.remaining' | 'billing.unknownModel' | 'billing.model' | 'billing.thModel' | 'billing.thInputMiss' | 'billing.thInputHit' | 'billing.currentRound' | 'billing.costAbbr' | 'billing.tabOverview' | 'billing.tabTrends' | 'billing.tabProviders' | 'billing.tabDetails' | 'billing.tabPricing' | 'billing.tabSettings' | 'billing.settingsHead' | 'billing.settingsHint' | 'billing.budgetHint' | 'billing.peakAlertHint' | 'billing.peakAlertDescPeak' | 'billing.peakAlertDescOff' | 'billing.export' | 'billing.exportCsvDay' | 'billing.exportCsvSession' | 'billing.exportJson' | 'billing.peakShare' | 'billing.peakShareHint' | 'billing.weekCost' | 'billing.roleCost' | 'billing.roleUser' | 'billing.roleAssistant' | 'billing.roleTool' | 'billing.roleHint' | 'billing.tierPeak' | 'billing.tierOff' | 'billing.tierToPeak' | 'billing.tierToOff' | 'billing.tierAlertEnterPeak' | 'billing.tierAlertEnterOff' | 'billing.peakAlertTitlePeak' | 'billing.peakAlertTitleOff' | 'billing.peakAlert' | 'billing.peakAlertLeadMin' | 'billing.peakAlertPos' | 'billing.peakAlertMode' | 'billing.peakAlertPosCorner' | 'billing.peakAlertPosCenter' | 'billing.peakAlertModePeak' | 'billing.peakAlertModeOff' | 'billing.peakAlertModeBoth' | 'billing.peakAlertWebNotify' | 'billing.peakAlertPreview' | 'billing.planTypeCode' | 'billing.planTypeToken' | 'billing.subscriptionFeePerMonth' | 'billing.triggerToday' | 'billing.triggerMonth' | 'billing.subscriptionIncluded' | 'billing.free' | 'billing.official' | 'billing.thirdParty' | 'billing.officialCost' | 'billing.thirdPartyCost' | 'billing.perfSamples' | 'billing.perfTtft' | 'billing.perfP50' | 'billing.perfP90' | 'billing.perfTps' | 'billing.perfLatency' | 'billing.perfEstimated' | 'billing.perfEmpty' | 'billing.perfTpsUnit' | 'billing.perfTitle' | 'billing.perfHint' | 'billing.heatmapYear' | 'billing.heatmapMonth' | 'billing.activeDays' | 'billing.streakDays' | 'billing.subscriptionAutoDetect' | 'billing.pluginInfo' | 'billing.pluginName' | 'billing.pluginDescription' | 'billing.pluginVersion' | 'billing.pluginAuthor' | 'billing.pluginRepository' | 'billing.pluginNpm' | 'billing.pluginLicense' | 'billing.tabToken' | 'billing.tokenExport' | 'billing.tokenExportCsv' | 'billing.tokenCacheHitRate' | 'billing.tokenReasoningShare' | 'billing.tokenReasoningShort' | 'billing.tokenIo' | 'billing.tokenPeak' | 'billing.tokenDaily' | 'billing.tokenByModel' | 'billing.tokenMiss' | 'billing.tokenHit' | 'billing.tokenOutput' | 'billing.tokenTotal' | 'billing.tokenShare' | 'billing.usageStatsTool' | 'billing.usageStatsToolHint' | 'billing.balanceGranted' | 'billing.balanceTopped' | 'billing.balanceDaily' | 'billing.balanceDaysLong' | 'billing.balanceDaysUnit' | 'billing.popTodayModel' | 'billing.popNoConsumption' | 'billing.popQuotaAlert' | 'billing.popRiskNone' | 'billing.popTitle' | 'billing.popDirectLead' | 'billing.popSubLead' | 'billing.popBalanceNormal' | 'billing.popBalanceLow' | 'billing.popQuotaNormal' | 'billing.popQuotaLow' | 'billing.alertBalanceLow' | 'billing.alertQuotaLow' | 'billing.unpricedHint' | 'billing.exportCsvSite' | 'billing.panelRelay' | 'billing.relaySite' | 'billing.relayDirect' | 'billing.relayUnknown' | 'billing.panelRelayQuota' | 'billing.relayBalance' | 'billing.relayNoQuota' | 'billing.relayWindowUsed' | 'billing.relayKindNewApi' | 'billing.relayKindSub2Api' | 'billing.relayKindUnknown' | 'billing.relayCalls';
 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,6 +12,10 @@
  * (weekdays 09:00-12:00 / 14:00-18:00 Beijing) at 2x the off-peak rate —
  * weekends (Sat/Sun, Beijing) are charged at the off-peak rate all day.
  * The estimator mixes both bands by a configured peak share ({@link DEFAULT_PEAK_SHARE}).
+ *
+ * Time-limited launch promos ({@link PricePromo}) never mutate the catalog:
+ * entries keep list price and a promo window; the estimator and the rate
+ * table apply the discount factor until the deadline, then auto-revert.
  */
 import type { LivePricing } from '../pricing-shared.ts';
 /**
@@ -124,6 +128,36 @@ export interface ModelPrice extends PriceBand {
     /** Off-peak band (Gemini Flex / DeepSeek 低谷档); absent = flat pricing. */
     offPeak?: PriceBand;
 }
+/**
+ * 限时促销窗口（新模型上线折扣等厂商营销活动）：生效期内该条目所有档位
+ * （主档与 offPeak）单价按 factor 折扣计价与显示，截止时刻起自动恢复刊例价。
+ */
+export interface PricePromo {
+    /** 折扣系数（0.5 = 五折）；仅 (0,1) 区间有效，非法值视为无促销。 */
+    factor: number;
+    /**
+     * 截止时刻（epoch ms）：该时刻及之后恢复刊例价。缺省表示厂商未公布截止日
+     * 的长期活动（如「限时 5 折直至另行通知」），持续生效直至收到公告后补填。
+     */
+    endsAtMs?: number;
+    /** 展示备注（如「限时 5 折至 …」），供界面提示活动性质。 */
+    note?: string;
+}
+/**
+ * 附加计价行（纯展示参考价）：承载主三桶之外的厂商计价维度，如 Batch
+ * 半价档、显式缓存创建/命中等。不参与估算计费——用量统计源只有
+ * input/cacheHit/cacheMiss/output 四桶，无 batch 与显式缓存维度可区分。
+ */
+export interface PriceRow {
+    /** 行标签（沿用目录单语风格，直接中文）。 */
+    label: string;
+    /** 输入侧单价（元或美元 / 每百万 token）；缺省显示 —。 */
+    input?: number;
+    /** 输出侧单价；缺省显示 —。 */
+    output?: number;
+    /** 补充说明（如与标准价的关系）。 */
+    note?: string;
+}
 /** One catalog entry: identity, brand color token, and price. */
 export interface ModelEntry {
     /** Model key used by `.dsh-usage-stats.json` `byModel`. */
@@ -138,6 +172,13 @@ export interface ModelEntry {
     price: ModelPrice;
     /** Peak-hour window label for time-of-day priced models. */
     peakHours?: string;
+    /**
+     * 限时促销：生效期内 price 各档位按 factor 打折，过期自动恢复。
+     * price 表本身永远保存刊例价，促销只在计价/显示出口处折算，不回写目录。
+     */
+    promo?: PricePromo;
+    /** 附加计价行（Batch / 显式缓存等展示性参考价），费率表在该模型行下方列出。 */
+    extraRows?: readonly PriceRow[];
     /**
      * 单价为估算价：厂商未公布按量官方单价（公测 / 套餐制），表内价格为估算，
      * 展示时标注以免误当正式定价；正式定价公布后移除。
@@ -193,12 +234,30 @@ export declare function modelOf(key: string): ModelEntry;
  * 聚合层的计价闸门（目录外模型不产生费用，避免兜底档误估）。
  */
 export declare function isPriced(key: string): boolean;
+/**
+ * 促销在 nowMs 是否生效：factor 必须落在 (0,1) 区间，截止时刻及之后视为过期；
+ * endsAtMs 缺省表示长期活动，在 factor 合法期间持续生效。
+ * 导出供测试：纯函数。
+ * @param promo - 待判定的促销窗口。
+ * @param nowMs - 判定时刻（epoch ms）。
+ */
+export declare function isPromoActive(promo: PricePromo, nowMs: number): boolean;
+/**
+ * 把限时促销折入条目单价：生效期内返回 price 主档与 offPeak 全部乘 factor 的
+ * 副本，其余字段原样保留；不在促销期（过期/未开始/factor 非法）原样返回。
+ * 幂等由调用方保证——计价与费率表显示各自只折一次，勿对已折价副本重复应用。
+ * @param entry - 目录条目（price 保持刊例价口径）。
+ * @param nowMs - 判定时刻（epoch ms）。
+ */
+export declare function applyPromo(entry: ModelEntry, nowMs: number): ModelEntry;
 /**
  * 费率表渲染的完整目录：内置 + models.dev 补充条目 + 探活模型（无价标记）。
- * 探活模型去重（按归一化 id）：内置/补充已有的不再重复；无价的保留并标记
- * `uncatalogued`，费率表据此显示「未收录」。
+ * 内置条目按 nowMs 折算限时促销（生效中的条目显示折后单价，过期自动恢复
+ * 刊例价）。探活模型去重（按归一化 id）：内置/补充已有的不再重复；无价的
+ * 保留并标记 `uncatalogued`，费率表据此显示「未收录」。
+ * @param nowMs - 促销判定时刻；缺省当前时刻。
  */
-export declare function catalogEntries(): readonly ModelEntry[];
+export declare function catalogEntries(nowMs?: number): readonly ModelEntry[];
 /** Resolve a price-table row by its CSS variable name (theme token or fallback color). */
 export declare function resolveToken(name: string): string;
 /**
@@ -216,11 +275,12 @@ export declare function resolveToken(name: string): string;
  * @param peakShare - share of traffic in the peak band (0..1); defaults to {@link DEFAULT_PEAK_SHARE}.
  * @returns the estimated cost in CNY.
  */
-export declare function computeCost(entry: ModelEntry, buckets: TokenUsageBuckets, peakShare?: number): number;
+export declare function computeCost(entry: ModelEntry, buckets: TokenUsageBuckets, peakShare?: number, nowMs?: number): number;
 /**
  * 按调用时刻精确判定高峰/空闲档并计价（P0-1：替代固定比例混合）。时刻未知
  * （null/NaN，理论不发生在真实事件流）时回退 {@link DEFAULT_PEAK_SHARE} 混合，
- * 保持旧语义不低估。平档模型（无 offPeak）两个时段同价。
+ * 保持旧语义不低估。平档模型（无 offPeak）两个时段同价。限时促销与峰谷档
+ * 同口径：按事件时刻判定该笔流量当时享受的单价。
  * @param entry - the catalog entry whose prices apply.
  * @param buckets - token usage counts.
  * @param timeMs - the call's wall-clock time (epoch ms); null falls back to the peak-share mix.

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": "1.0.2",
+  "version": "1.0.3",
   "publishConfig": {
     "access": "public"
   },