@kenz1117/dsh-ui-usage-billing 1.0.12 → 1.0.13

package/lib/index.js

@@ -7,6 +7,7 @@ import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { settingsNamespace } from "@deepseek-ai/dsh-settings";
 import z from "@deepseek-ai/schemastery";
+import { createHash, createHmac } from "node:crypto";
 //#region lib/types/client/plan-knowledge.js
 /**
 * Plan-knowledge reference (adapted from dsh-spend's `knowledge.js`, MIT):
@@ -2914,6 +2915,26 @@ const QUERIERS = [
 		route: "zai-coding-cn",
 		displayName: "智谱 AI",
 		querier: queryZhipu
+	},
+	{
+		route: "tencent-tokenhub",
+		displayName: "腾讯云 TokenHub",
+		querier: queryTencentTokenPlan
+	},
+	{
+		route: "tokenhub",
+		displayName: "腾讯云 TokenHub",
+		querier: queryTencentTokenPlan
+	},
+	{
+		route: "tencent",
+		displayName: "腾讯云 TokenHub",
+		querier: queryTencentTokenPlan
+	},
+	{
+		route: "tencentcloud",
+		displayName: "腾讯云 TokenHub",
+		querier: queryTencentTokenPlan
 	}
 ];
 /**
@@ -2946,6 +2967,200 @@ async function queryBalances(ctx, providers) {
 		return querier(ctx, env);
 	}));
 }
+/** TokenHub 管控面 API 端点（cloud.tencent.cn/document/api/1823/132270）。 */
+const TOKENHUB_HOST = "tokenhub.tencentcloudapi.com";
+/** 云 API 3.0 产品名与版本（签名的 service 段与请求头都必须一致）。 */
+const TOKENHUB_SERVICE = "tokenhub";
+const TOKENHUB_VERSION = "2026-03-22";
+/** 请求地域：管控面对地域不敏感，取默认国内地域（文档地域列表含 ap-guangzhou）。 */
+const TOKENHUB_REGION = "ap-guangzhou";
+/** 腾讯云凭据引用值格式：`<SecretId>:<SecretKey>`（分隔符取首个冒号）。 */
+function parseTencentCredential(value) {
+	const sep = value.indexOf(":");
+	if (sep === -1) return void 0;
+	const secretId = value.slice(0, sep).trim();
+	const secretKey = value.slice(sep + 1).trim();
+	if (secretId === "" || secretKey === "") return void 0;
+	return {
+		secretId,
+		secretKey
+	};
+}
+/**
+* 构造云 API 3.0 TC3-HMAC-SHA256 签名（官方签名方法 v3）。导出供测试：纯函数，
+* 输入确定则签名确定。Action 不参与签名——它走 `X-TC-Action` 请求头。
+* @param secretId - 云 API SecretId。
+* @param secretKey - 云 API SecretKey。
+* @param payload - 已序列化的请求体（含 Action/Version/Region 公共参数）。
+* @param timestamp - 签名时间戳（秒）。
+* @returns Authorization 头的值。
+*/
+function tc3Authorization(secretId, secretKey, payload, timestamp) {
+	const date = (/* @__PURE__ */ new Date(timestamp * 1e3)).toISOString().slice(0, 10);
+	const canonicalRequest = `POST\n/\n\n${`content-type:application/json; charset=utf-8\nhost:${TOKENHUB_HOST}\n`}\ncontent-type;host\n${createHash("sha256").update(payload).digest("hex")}`;
+	const hashedCanonical = createHash("sha256").update(canonicalRequest).digest("hex");
+	const stringToSign = `TC3-HMAC-SHA256\n${String(timestamp)}\n${date}/${TOKENHUB_SERVICE}/tc3_request\n${hashedCanonical}`;
+	return `TC3-HMAC-SHA256 Credential=${secretId}/${date}/${TOKENHUB_SERVICE}/tc3_request, SignedHeaders=content-type;host, Signature=${createHmac("sha256", createHmac("sha256", createHmac("sha256", createHmac("sha256", date).update(secretKey).digest()).update(TOKENHUB_SERVICE).digest()).update("tc3_request").digest()).update(stringToSign).digest("hex")}`;
+}
+/** 调用一次 TokenHub 管控面接口：TC3 签名 + 超时保护，返回响应 JSON 的 `Response`。 */
+async function callTokenHub(secretId, secretKey, action, params) {
+	const payload = JSON.stringify({
+		Action: action,
+		Version: TOKENHUB_VERSION,
+		Region: TOKENHUB_REGION,
+		...params
+	});
+	const timestamp = Math.floor(Date.now() / 1e3);
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS$3);
+	try {
+		const response = await fetch(`https://${TOKENHUB_HOST}/`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json; charset=utf-8",
+				host: TOKENHUB_HOST,
+				"x-tc-action": action.toLowerCase(),
+				"x-tc-version": TOKENHUB_VERSION,
+				"x-tc-region": TOKENHUB_REGION,
+				"x-tc-timestamp": String(timestamp),
+				authorization: tc3Authorization(secretId, secretKey, payload, timestamp)
+			},
+			body: payload,
+			signal: controller.signal
+		});
+		if (response.status === 401 || response.status === 403) throw Object.assign(/* @__PURE__ */ new Error("unauthorized"), { code: "unauthorized" });
+		if (!response.ok) throw Object.assign(/* @__PURE__ */ new Error(`HTTP ${String(response.status)}`), {
+			httpStatus: response.status,
+			code: "unreachable"
+		});
+		const inner = (await response.json()).Response;
+		if (inner === void 0) throw Object.assign(/* @__PURE__ */ new Error("no Response envelope"), { code: "invalid" });
+		if (inner.Error !== void 0 && inner.Error !== null) {
+			const err = inner.Error;
+			const code = err.Code === "AuthFailure.SignatureFailure" || err.Code === "AuthFailure.SecretIdNotFound" ? "unauthorized" : "unreachable";
+			throw Object.assign(new Error(String(err.Code ?? "api-error")), { code });
+		}
+		return inner;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* 在套餐余量对象里防御性提取「剩余额度」：官方 SubPackageBalance/PackageInfo
+* 的字段名未稳定公开（issue #18 调研期），按语义键名扫描——命中 remaining /
+* balance / left 语义键直接用；命中 total 与 used 则相减推导。数字一律经
+* {@link toNumber} 归一化（上游可能给字符串）。
+* 导出供测试：纯函数。
+* @param source - 套餐详情里的余量对象（PackageInfo / SubPackageBalance 等）。
+* @returns 剩余额度（上游单位，通常为 token 数或元）；提取不到返回 undefined。
+*/
+function pickRemainingQuota(source) {
+	if (source === null || typeof source !== "object") return void 0;
+	const numeric = Object.entries(source).filter(([, v]) => v !== null && toNumber$1(v) !== void 0);
+	const byKey = (needles) => {
+		for (const [key, value] of numeric) {
+			const lower = key.toLowerCase();
+			if (needles.some((n) => lower.includes(n))) {
+				const num = toNumber$1(value);
+				if (num !== void 0 && num >= 0) return num;
+			}
+		}
+	};
+	const remaining = byKey([
+		"remain",
+		"balance",
+		"left",
+		"available"
+	]);
+	if (remaining !== void 0) return remaining;
+	const total = byKey(["total"]);
+	const used = byKey(["used", "consume"]);
+	if (total !== void 0 && used !== void 0) return Math.max(0, total - used);
+}
+/** 套餐列表里提取第一个启用套餐的 TeamId：集合字段名做候选兼容。 */
+function firstEnabledTeamId(inner) {
+	const candidates = inner.TeamSet ?? inner.TokenPlanSet ?? inner.PlanSet;
+	if (!Array.isArray(candidates)) return void 0;
+	for (const item of candidates) {
+		if (item === null || typeof item !== "object") continue;
+		const row = item;
+		if (row.TeamId === void 0 && row.PlanId === void 0) continue;
+		if (row.Status !== void 0 && row.Status !== "enable") continue;
+		const id = row.TeamId ?? row.PlanId;
+		if (typeof id === "string" && id !== "") return id;
+	}
+}
+/**
+* 查询腾讯云 TokenHub Token Plan 套餐余量。凭据值格式 `<SecretId>:<SecretKey>`
+* （云 API 密钥，非 TokenHub 推理 key）。链路：套餐列表取 TeamId → 套餐详情读
+* 主额度包余量。管控面字段名未完全稳定，解析按语义键防御提取。
+* @param ctx - host context carrying the credentials seam.
+* @param apiKeyEnv - credential reference resolving the `<SecretId>:<SecretKey>` pair.
+*/
+async function queryTencentTokenPlan(ctx, apiKeyEnv) {
+	const provider = "腾讯云 TokenHub";
+	const hit = await ctx.credentials.resolve(credentialRef(apiKeyEnv));
+	if (hit === void 0) return {
+		provider,
+		displayName: provider,
+		error: "unconfigured"
+	};
+	if (!balanceGate.check(provider)) return {
+		provider,
+		displayName: provider,
+		error: "unreachable"
+	};
+	const credential = parseTencentCredential(hit.value);
+	if (credential === void 0) return {
+		provider,
+		displayName: provider,
+		error: "unauthorized"
+	};
+	const doRequest = async () => {
+		const teamId = firstEnabledTeamId(await callTokenHub(credential.secretId, credential.secretKey, "DescribeTokenPlanList", {}));
+		if (teamId === void 0) return {
+			provider,
+			displayName: provider,
+			error: "invalid"
+		};
+		const detail = await callTokenHub(credential.secretId, credential.secretKey, "DescribeTokenPlan", { TeamId: teamId });
+		const remaining = pickRemainingQuota(detail.PackageInfo) ?? pickRemainingQuota(detail);
+		if (remaining === void 0) {
+			console.warn(`[usage-billing] balance response drifted for ${provider}: no remaining-quota field parsed`);
+			return {
+				provider,
+				displayName: provider,
+				error: "invalid"
+			};
+		}
+		const plan = typeof detail.Name === "string" ? detail.Name : void 0;
+		const exhausted = detail.StopReason === "EXHAUSTED";
+		return {
+			provider,
+			displayName: provider,
+			currency: "CNY",
+			totalBalance: remaining,
+			...plan !== void 0 ? { plan } : {},
+			...exhausted ? { isAvailable: false } : {}
+		};
+	};
+	try {
+		const row = await withRetry(doRequest, {
+			retries: 1,
+			baseDelayMs: 250,
+			maxDelayMs: 2e3
+		});
+		balanceGate.success(provider);
+		return row;
+	} catch (error) {
+		balanceGate.fail(provider);
+		return {
+			provider,
+			displayName: provider,
+			error: error.code === "unauthorized" ? "unauthorized" : "unreachable"
+		};
+	}
+}
 /** 点路径取值：`data.total_available` → 逐层下钻；任一缺失返回 undefined。 */
 function getPath(data, path) {
 	let cursor = data;

package/lib/types/balance.d.ts

@@ -25,6 +25,26 @@ import type { CustomBalanceConfig, CustomBalanceExtract, ProviderBalance } from
 export declare function queryBalances(ctx: Context, providers: Readonly<Record<string, {
     apiKeyEnv?: string;
 }>>): Promise<readonly ProviderBalance[]>;
+/**
+ * 构造云 API 3.0 TC3-HMAC-SHA256 签名（官方签名方法 v3）。导出供测试：纯函数，
+ * 输入确定则签名确定。Action 不参与签名——它走 `X-TC-Action` 请求头。
+ * @param secretId - 云 API SecretId。
+ * @param secretKey - 云 API SecretKey。
+ * @param payload - 已序列化的请求体（含 Action/Version/Region 公共参数）。
+ * @param timestamp - 签名时间戳（秒）。
+ * @returns Authorization 头的值。
+ */
+export declare function tc3Authorization(secretId: string, secretKey: string, payload: string, timestamp: number): string;
+/**
+ * 在套餐余量对象里防御性提取「剩余额度」：官方 SubPackageBalance/PackageInfo
+ * 的字段名未稳定公开（issue #18 调研期），按语义键名扫描——命中 remaining /
+ * balance / left 语义键直接用；命中 total 与 used 则相减推导。数字一律经
+ * {@link toNumber} 归一化（上游可能给字符串）。
+ * 导出供测试：纯函数。
+ * @param source - 套餐详情里的余量对象（PackageInfo / SubPackageBalance 等）。
+ * @returns 剩余额度（上游单位，通常为 token 数或元）；提取不到返回 undefined。
+ */
+export declare function pickRemainingQuota(source: unknown): number | undefined;
 /**
  * 按 extract 规则从响应 JSON 求值。导出供测试：纯函数。
  * @param rule - 提取规则（const / path / add / subtract / divide）。

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.promoBadge' | 'billing.promoUntil' | 'billing.promoOpenEnded' | 'billing.pricingTip' | 'billing.pricingUnit' | 'billing.pricingNotes' | 'billing.ubPeak' | 'billing.ubOff' | 'billing.ubStd' | '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.cardDisplay' | 'billing.cardDisplayHint' | 'billing.cardMetric' | 'billing.cardMetricMoney' | 'billing.cardMetricTokens' | 'billing.triggerMonthTokens' | 'billing.floatPrev' | 'billing.floatNext' | 'billing.subscriptionsStale' | 'billing.staleLedgerNotice' | 'billing.tokenCacheWrite' | 'billing.toolRank' | 'billing.toolName' | 'billing.userPrices' | 'billing.userPricesHint' | 'billing.userPriceSave' | 'billing.userPriceModel' | 'billing.userPriceSource' | 'billing.userPriceSourceHint' | 'billing.userPriceCurrency' | 'billing.userPriceAdd' | 'billing.userPriceRemove' | 'billing.sessionStaleBadge' | '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.peakSharePerCall' | 'billing.offPeakSavings' | 'billing.perfMax' | '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.searchEstimateHint' | 'billing.siteListDisplay' | 'billing.siteListDisplayHint' | '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.ubStd' | '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.cardDisplay' | 'billing.cardDisplayHint' | 'billing.cardMetric' | 'billing.cardMetricMoney' | 'billing.cardMetricTokens' | 'billing.triggerMonthTokens' | 'billing.floatPrev' | 'billing.floatNext' | 'billing.subscriptionsStale' | 'billing.staleLedgerNotice' | 'billing.tokenCacheWrite' | 'billing.toolRank' | 'billing.toolName' | 'billing.userPrices' | 'billing.userPricesHint' | 'billing.userPriceSave' | 'billing.userPriceModel' | 'billing.userPriceSource' | 'billing.userPriceSourceHint' | 'billing.userPriceOffPeak' | 'billing.userPriceCurrency' | 'billing.userPriceAdd' | 'billing.userPriceRemove' | 'billing.sessionStaleBadge' | '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.peakSharePerCall' | 'billing.offPeakSavings' | 'billing.perfMax' | '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.searchEstimateHint' | 'billing.siteListDisplay' | 'billing.siteListDisplayHint' | '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

@@ -41,6 +41,12 @@ export interface UserPrice {
     output: number;
     /** 计价币种；缺省 CNY。 */
     currency?: 'CNY' | 'USD';
+    /** 低谷档三桶（元或美元 / 每百万 token）；缺省 = 平档（峰谷同价）。 */
+    offPeak?: {
+        input: number;
+        cacheHit: number;
+        output: number;
+    };
 }
 /** 一条用户自定义价：绑定「模型（计费目录键）+ 可选来源（中转站 origin）」。
  *  origin 缺省 = 该模型的默认价；带 origin = 仅该中转站的同名模型用此价。 */
@@ -50,6 +56,22 @@ export interface UserPriceEntry extends UserPrice {
     /** 绑定来源（中转站 origin，如 `https://api.my-relay.com`）；缺省 = 默认价。 */
     origin?: string;
 }
+/**
+ * 中转站 origin 宽松匹配：双方规范化到 `protocol://host[:port]` 后比较。
+ * 宿主侧站点桶的 origin 来自 `new URL(baseURL).origin`，用户手填的来源常缺
+ * 协议、带路径或尾斜杠——精确全等会让自定义价静默失效（issue #18）。
+ * 规范化失败（无法解析成 URL）时回退小写去尾斜杠的字面比较。
+ * @param a - 用户录入的来源（可缺协议/带路径）。
+ * @param b - 宿主站点桶的 origin（`new URL().origin` 形态）。
+ */
+/**
+ * 把用户手填的中转站来源规范化为 `protocol://host[:port]` 形态：缺协议补
+ * `https://`、带路径取 origin。无法解析时回退小写去尾斜杠的字面值。
+ * 与 {@link originsMatch} 的比较口径一致——保存前规范化一次，匹配时双向兜底。
+ * @param raw - 用户录入的来源（可缺协议/带路径）。
+ */
+export declare function normalizeOriginInput(raw: string): string;
+export declare function originsMatch(a: string, b: string): boolean;
 /**
  * 注入用户自定义单价列表。每条含模型目录键 + 可选来源（origin）。空数组 = 清除全部
  * 自定义价，回退内置目录。
@@ -65,6 +87,20 @@ export declare function getUserPrices(): Readonly<UserPriceEntry[]> | undefined;
  * @param origin - 调用来源（中转站 origin）；缺省仅查默认价。
  */
 export declare function userPriceOf(key: string, origin?: string): UserPrice | undefined;
+/**
+ * 查一个模型（可选来源）的完整用户价条目（含 origin 绑定信息）。
+ * 匹配优先级：origin 宽松精确命中（模型×来源）→ 无来源默认价。
+ * @param key - 计费目录键。
+ * @param origin - 调用来源（中转站 origin）；缺省仅查默认价。
+ */
+export declare function userPriceEntryOf(key: string, origin?: string): UserPriceEntry | undefined;
+/**
+ * 查一个模型的「带来源」用户价条目（无视来源值，取第一条命中模型名的
+ * 带 origin 条目）。供 recost 在三维站点数据缺失时兜底：用户填了来源价
+ * 就按它重估，而不是静默回退宿主原价（issue #18）。
+ * @param key - 计费目录键。
+ */
+export declare function userOriginPriceEntryOf(key: string): UserPriceEntry | undefined;
 /**
  * Apply the node half's live pricing snapshot. Absent fields keep the
  * built-in catalog and rate; callers never fabricate values.

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.12",
+  "version": "1.0.13",
   "publishConfig": {
     "access": "public"
   },