@kenz1117/dsh-ui-usage-billing 0.4.2 → 0.5.0

package/lib/index.js

@@ -272,7 +272,8 @@ const MODEL_CATALOG = [
 			input: 4,
 			cacheHit: .4,
 			output: 12
-		}
+		},
+		estimated: true
 	},
 	{
 		key: "minimax",
@@ -356,7 +357,8 @@ const MODEL_CATALOG = [
 			input: 5,
 			cacheHit: .5,
 			output: 10
-		}
+		},
+		estimated: true
 	},
 	{
 		key: "sensenova",
@@ -368,7 +370,8 @@ const MODEL_CATALOG = [
 			input: 4.5,
 			cacheHit: .45,
 			output: 9
-		}
+		},
+		estimated: true
 	},
 	{
 		key: "baichuan",
@@ -1684,6 +1687,7 @@ const inject = [
 * 订阅 provider id（llm-pi-ai 设置键）→ billing 适配器 key 的映射。
 * 复用 dsh 既有的 llm-pi-ai provider 配置（apiKeyEnv 引用），不引入新配置面。
 */
+/** key 只取字符串凭据字段：zaiRegion 是区域枚举，由下方区域逻辑单独赋值。 */
 const SUBSCRIPTION_KEY_SOURCES = [
 	{
 		provider: "kimi-coding",

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

@@ -8,6 +8,7 @@
  * A hover crosshair shows the day's model breakdown. No chart library — the
  * surface stays self-contained and offline.
  */
+import { type CostCurrency } from './pricing.ts';
 /** One model's legend identity: key, display name, and brand color. */
 export interface TrendSeriesModel {
     /** Stats key (`byModel` key), also the `byModel` map key. */
@@ -32,9 +33,11 @@ export interface TrendPoint {
  * Render the daily stacked cost bars plus the total-calls line.
  * @param props.data - sorted daily rows (ascending date).
  * @param props.models - the model legend, in bar order.
+ * @param props.currency - display currency for the cost labels.
  */
-export declare function TrendChart({ data, models }: {
+export declare function TrendChart({ data, models, currency }: {
     data: readonly TrendPoint[];
     models?: readonly TrendSeriesModel[];
+    currency?: CostCurrency;
 }): React.ReactNode;
 //# sourceMappingURL=TrendChart.d.ts.map

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

@@ -12,22 +12,33 @@
 import type { InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots';
 import type { SidebarFooterActionOwnerProps } from '@deepseek-ai/dsh-client-ui-sidebar/client';
 import type { createBillingBudgetStore } from './budget-store.ts';
-import { NS } from './locales.ts';
+import { NS, type UsageBillingKey } from './locales.ts';
 /** Model-connectivity health reported by the host model directory probe. */
 export interface ModelHealth {
     /** Whether the probe completed (false while still loading). */
     checked: boolean;
     /** True when at least one connected provider answered its model catalog. */
     available: boolean;
-    /** Connected provider count. */
-    providers: number;
-    /** Provider count whose catalog probe failed. */
+    /** 可用模型总数：累加每个厂商成功 advertise 的模型数，而非厂商数。 */
+    models: number;
+    /** 失效厂商数（目录探测失败的厂商；失败信息不细分到模型级）。 */
     failures: number;
     /** Display names of providers that answered their model catalog (live). */
     okProviders: readonly string[];
     /** Display names of providers whose catalog probe failed. */
     badProviders: readonly string[];
 }
+/** 仪表盘分区 Tab id。 */
+export type DashboardTab = 'overview' | 'trends' | 'providers' | 'details' | 'pricing';
+/**
+ * Tab 定义（顺序即渲染顺序）：概览=主数字/预算/KPI/热力图，趋势=趋势图/每轮费用，
+ * 厂商=厂商计费与订阅，明细=工作区/会话明细，单价=模型单价表。导出供测试断言
+ * tab 与文案 key 对齐、decor 锚点落在正确分区。
+ */
+export declare const DASHBOARD_TABS: readonly {
+    id: DashboardTab;
+    labelKey: UsageBillingKey;
+}[];
 /**
  * The dashboard's display names (中文厂商名) never equal the provider names a
  * user actually configures (deepseek, zhipu, qwen…), so the dot match also
@@ -44,6 +55,18 @@ export declare const PROVIDER_ALIASES: Readonly<Record<string, readonly string[]
  * 导出供守卫测试：短别名（mi/yi）仅允许前缀形式，防止 minimax 等误吞。
  */
 export declare function providerFromModelKey(modelKey: string): string | undefined;
+/**
+ * 本月预计总花费：按本月已有记录的平均日消耗 × 本月天数外推；无本月记录时
+ * 回退为最近 7 天日均 × 本月天数；无任何记录时返回 0（调用方不展示）。
+ * 导出供测试：纯函数，不依赖组件。
+ * @param byDay - 按日费用表。
+ * @param monthPrefix - 本月前缀（YYYY-MM）。
+ * @param today - 今日日期戳（YYYY-MM-DD）。
+ * @returns 本月预计花费（人民币元）；无数据时为 0。
+ */
+export declare function projectMonthCost(byDay: Record<string, {
+    cost: number;
+}>, monthPrefix: string, today: string): number;
 /** 组件注入面：探活 + 计费指标写入（billing 自身写入，主题插件经服务读取）。 */
 export interface UsageBillingInjected {
     checkModels: () => Promise<ModelHealth>;

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

@@ -0,0 +1,52 @@
+/**
+ * Cost-spike anomaly detection (pure): marks turns whose cost exceeds a
+ * rolling baseline, with attribution chips. Shared by the per-turn chart and
+ * any future surface; kept free of React so it unit-tests without a host.
+ *
+ * Adapted from the community dsh-usage-chart flagAnomalies semantics: the
+ * baseline is the previous up-to-`window` turns (rows without a cost are
+ * skipped, so the window counts effective rows).
+ */
+/** 异常归因 chip：输出增长 / 上下文膨胀 / 缓存命中率下降。 */
+export type AnomalyReason = 'output-growth' | 'context-bloat' | 'cache-hit-drop';
+/** 一轮异常标记（按会话+轮次定位）。 */
+export interface AnomalyFlag {
+    /** 会话 id（与数据行一致，用于定位该轮）。 */
+    sessionId: string;
+    /** 会话内轮次号。 */
+    turn: number;
+    /** 该轮成本（人民币元）。 */
+    cost: number;
+    /** 归因原因（可为空：只有突增事实、无明确归因）。 */
+    reasons: readonly AnomalyReason[];
+}
+/** 异常判定所需的每轮数据形状（TurnUsageRow 的子集）。 */
+export interface AnomalyRound {
+    sessionId: string;
+    turn: number;
+    /** 该轮成本；未估算（订阅/未知）时可为 0——基线窗口跳过 0 成本轮。 */
+    cost: number;
+    output: number;
+    input: number;
+    cacheHit: number;
+    cacheMiss: number;
+}
+/** 异常判定调参。 */
+export interface AnomalyOptions {
+    /** 对比窗口：取该轮之前至多 window 轮做基线。默认 6。 */
+    window?: number;
+    /** 突增阈值：成本超过基线均值 × threshold 即标记。默认 2。 */
+    threshold?: number;
+    /** 归因阈值：输出/输入超过基线均值 × 该值归因为增长。默认 1.8。 */
+    reasonFactor?: number;
+    /** 归因阈值：缓存命中率低于基线该百分点归因为下降。默认 15。 */
+    reasonHitDropPp?: number;
+}
+/**
+ * 标记成本异常轮次（按时间顺序传入；最近的轮次排在末尾）。
+ * @param rounds - 按起始时间升序的轮次序列（最早在前）。
+ * @param options - 窗口/阈值/归因灵敏度。
+ * @returns 异常标记数组（保持输入顺序）。
+ */
+export declare function flagAnomalies(rounds: readonly AnomalyRound[], options?: AnomalyOptions): AnomalyFlag[];
+//# sourceMappingURL=anomaly.d.ts.map

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

@@ -0,0 +1,35 @@
+/**
+ * UsageHeatmap: dependency-free month calendar heatmap of daily cost.
+ *
+ * Styled after an "activity map": one large rounded cell per day with the
+ * date number printed inside, laid out in a 7-column grid (Sunday-first).
+ * Week-first data layout: each week is one array element of 7 cells, so the
+ * grid auto-rows place them correctly without per-cell gridColumnStart hacks.
+ * Cell intensity is the day's cost quantized to five levels against the month
+ * maximum (mint-green gradient, like the reference activity map). Leading
+ * slots before the 1st and trailing slots after the last day carry the
+ * cross-month dates as gray placeholders; future days of this month render as
+ * gray placeholders too. Hover shows the exact date and amount.
+ */
+import { type CostCurrency } from './pricing.ts';
+/** One heatmap day. */
+export interface HeatmapDay {
+    /** ISO date `YYYY-MM-DD` (local calendar). */
+    date: string;
+    /** Value to intensity-map (daily cost in CNY). */
+    value: number;
+}
+/**
+ * Render the month heatmap.
+ * @param props.days - daily cost rows (keys are `YYYY-MM-DD`).
+ * @param props.currency - display currency for the hover amount.
+ * @param props.now - anchor date (defaults to today); injectable for tests.
+ * @param props.t - locale function (used for the legend labels).
+ */
+export declare function UsageHeatmap({ days, currency, now, t }: {
+    days: readonly HeatmapDay[];
+    currency: CostCurrency;
+    now?: Date;
+    t: (key: 'billing.costAbbr' | 'billing.noData' | 'billing.heatmapLess' | 'billing.heatmapMore') => string;
+}): React.ReactNode;
+//# sourceMappingURL=heatmap.d.ts.map

package/lib/types/client/live-cost.d.ts

@@ -0,0 +1,55 @@
+/**
+ * LiveCostBar: the session-scope cost ticker mounted on the composer's dock,
+ * showing the current session's accumulated spend and the latest turn's cost.
+ *
+ * It rides `conversation.composer.dock` (the stats-line family seat under the
+ * composer card, same posture as ui-conversation's own StatsLine), so it stays
+ * visible while working without opening the full dashboard. Data comes from the
+ * same `/api/billing/usage-stats` endpoint the dashboard polls; the bar reads
+ * the current session id off the framework snapshot (`useSession` parent of
+ * `sessionId`) and matches `bySession` (session total) and `byTurn` (latest
+ * turn cost). Rendering is a pure function of the snapshot, never a side effect.
+ */
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client';
+/** The usage-stats shape the composer bar needs (a thin slice, not the whole doc). */
+export interface LiveStats {
+    bySession?: readonly {
+        id: string;
+        cost: number;
+    }[];
+    byTurn?: readonly {
+        sessionId: string;
+        turn: number;
+        cost: number;
+    }[];
+}
+/**
+ * 当前会话累计费用：bySession 里会话 id 匹配的那行；缺省为 0。
+ * 导出供测试：纯函数。
+ * @param stats - 薄统计切片。
+ * @param sessionId - 当前会话 id。
+ * @returns 该会话累计费用（人民币元）。
+ */
+export declare function sessionCostOf(stats: LiveStats | null, sessionId: string | undefined): number;
+/**
+ * 当前轮费用：byTurn 里该会话最新一轮的 cost；缺省为 0。
+ * byTurn 服务端按起始时间倒序下发，但求 max(turn) 更稳健（不依赖顺序）。
+ * 导出供测试：纯函数。
+ * @param stats - 薄统计切片。
+ * @param sessionId - 当前会话 id。
+ * @returns 最新一轮费用（人民币元）。
+ */
+export declare function turnCostOf(stats: LiveStats | null, sessionId: string | undefined): number;
+/** Props: the session-scope snapshot selector the framework injects. */
+export interface LiveCostBarProps {
+    useSession: SnapshotSelectorHook<ConversationSnapshot>;
+    /** The owning dock's locale seat (bound to the billing NS). */
+    t: (key: 'billing.liveTurn' | 'billing.liveSession') => string;
+}
+/**
+ * Render the live cost ticker for the current session.
+ * @param props - framework session snapshot hook and locale.
+ */
+export declare function LiveCostBar({ useSession, t }: LiveCostBarProps): React.ReactNode;
+//# sourceMappingURL=live-cost.d.ts.map

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.trend7d' | 'billing.trend30d' | 'billing.trendEmpty' | 'billing.budget' | 'billing.sessions' | 'billing.project' | 'billing.lastActive' | 'billing.sessionOverflow' | 'billing.budgetOverBody' | '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' | 'billing.uncatalogued' | 'billing.balanceDays' | 'billing.balanceLowBody';
+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.trendEmpty' | 'billing.budget' | 'billing.sessions' | 'billing.project' | 'billing.lastActive' | 'billing.sessionOverflow' | 'billing.budgetOverBody' | '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.lastUpdated' | 'billing.noData' | 'billing.todayRate' | 'billing.rateLive' | 'billing.rateBuiltin' | 'billing.balance' | 'billing.balanceUnconfigured' | 'billing.balanceUnauthorized' | 'billing.balanceUnreachable' | 'billing.uncatalogued' | 'billing.estimatedPricing' | 'billing.balanceDays' | 'billing.balanceLowBody' | 'billing.subscriptions' | 'billing.subscriptionNotConfigured' | 'billing.subscriptionUnauthorized' | 'billing.subscriptionUnavailable' | 'billing.subscriptionInvalid' | 'billing.subscriptionRateLimited' | 'billing.subscriptionSession' | 'billing.subscriptionWeekly' | 'billing.subscriptionMonthly' | 'billing.subscriptionBilling' | 'billing.subscriptionRemaining' | 'billing.subscriptionReset' | 'billing.subscriptionNoApi' | 'billing.heatmapLess' | 'billing.heatmapMore' | 'billing.currency' | 'billing.currencyCny' | 'billing.currencyUsd' | 'billing.heatmap' | 'billing.rounds' | 'billing.anomaly' | 'billing.workspaces' | 'billing.plan' | 'billing.remaining' | 'billing.unknownModel' | 'billing.model' | 'billing.currentRound' | 'billing.costAbbr' | 'billing.tabOverview' | 'billing.tabTrends' | 'billing.tabProviders' | 'billing.tabDetails' | 'billing.tabPricing';
 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

@@ -95,6 +95,11 @@ export interface ModelEntry {
     price: ModelPrice;
     /** Peak-hour window label for time-of-day priced models. */
     peakHours?: string;
+    /**
+     * 单价为估算价：厂商未公布按量官方单价（公测 / 套餐制），表内价格为估算，
+     * 展示时标注以免误当正式定价；正式定价公布后移除。
+     */
+    estimated?: boolean;
 }
 /**
  * Built-in catalog of current mainstream models as of 2026-08-16, priced from

package/lib/types/client/round-chart.d.ts

@@ -0,0 +1,37 @@
+/**
+ * RoundCostChart: dependency-free per-turn cost bars with spike markers.
+ *
+ * One bar per turn (most recent N, newest last), height scaled to the window
+ * maximum. Turns flagged by {@link flagAnomalies} get a warning outline and a
+ * corner marker; hover shows the turn's model, cost, and window time. Styling
+ * lives in the billing CSS module (`.rounds*`).
+ */
+import type { AnomalyFlag } from './anomaly.ts';
+import { type CostCurrency } from './pricing.ts';
+/** 每轮费用图的一行（TurnUsageRow 的展示子集）。 */
+export interface RoundChartRow {
+    sessionId: string;
+    turn: number;
+    model: string;
+    cost: number;
+    input: number;
+    output: number;
+    cacheHit: number;
+    cacheMiss: number;
+    startedAt: number;
+    endedAt?: number;
+}
+/**
+ * Render the per-turn cost bars.
+ * @param props.rounds - turns, most recent last (ascending startedAt); oldest beyond the limit are dropped.
+ * @param props.flags - spike flags matched by sessionId+turn.
+ * @param props.currency - display currency for the amount labels.
+ * @param props.t - locale function for the model label.
+ */
+export declare function RoundCostChart({ rounds, flags, currency, t }: {
+    rounds: readonly RoundChartRow[];
+    flags: readonly AnomalyFlag[];
+    currency: CostCurrency;
+    t: (key: 'billing.model' | 'billing.costAbbr') => string;
+}): React.ReactNode;
+//# sourceMappingURL=round-chart.d.ts.map

package/lib/types/index.d.ts

@@ -12,7 +12,8 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { CredentialProvider } from '@deepseek-ai/dsh-credentials';
 import type { SettingsProvider } from '@deepseek-ai/dsh-settings';
-import { type IdentifiedSubscriptionPlan, type SubscriptionKeys, type SubscriptionPlanConfig } from './subscriptions.ts';
+import type { SubscriptionPlanConfig } from './pricing-shared.ts';
+import { type IdentifiedSubscriptionPlan, type SubscriptionKeys } from './subscriptions.ts';
 /** Plugin configuration. */
 export interface UsageBillingConfig {
     /** Absolute path to a `.dsh-usage-stats.json` fallback file. */

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