@kenz1117/dsh-ui-usage-billing 1.5.1 → 1.6.1

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

@@ -15,7 +15,7 @@
  */
 import type { UsageBillingKey } from './locales.ts';
 import type { TrendSeriesModel } from './TrendChart.tsx';
-import type { UsageStats } from './UsageBilling.tsx';
+import type { UsageStats } from './domain/types.ts';
 /** 短数字刻度：`1.2M` / `3.4K`。导出供概览 KPI 峰值日卡复用。 */
 export declare function shortNumber(v: number): string;
 /** 每日 token 堆叠图元（按结构视角）。 */

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

@@ -8,357 +8,17 @@
  * table. Data comes from the host's `/api/billing/usage-stats` endpoint;
  * before real data arrives the dashboard shows an empty (zero) snapshot,
  * never fabricated samples.
+ *
+ * v1.5.2 拆分（refactor）：纯函数 / 类型 / fetch 抽到 `client/domain/` 与
+ * `client/api/`，常量抽到 `client/constants.ts`，本文件只保留组件本身
+ * （UsageBilling / BillingDashboard / UsageBillingTrigger / UserPriceCard /
+ * PositionMenu / SubscriptionWindowRow / BalanceDetailPopover+Row）。
  */
 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 ClientPerf } from './PerfPanel.tsx';
 import type { createBillingBudgetStore } from './budget-store.ts';
-import { type CatalogModel } from './pricing.ts';
-import type { ReconcileNotice } from '../pricing-shared.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;
-    /** 可用模型总数：累加每个厂商成功 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[];
-    /** 探活得到的模型清单（系统里实际配置/预制的模型；无价格，费率表据此对标）。 */
-    catalog?: readonly CatalogModel[];
-}
-/** 仪表盘分区 Tab id。 */
-export type DashboardTab = 'overview' | 'token' | 'trends' | 'providers' | 'pricing' | 'settings';
-/**
- * Tab 定义（顺序即渲染顺序）：概览=主数字/KPI/热力图，账单=厂商计费与订阅，
- * 用量=Token 用量，趋势=趋势图/每轮费用，费率=模型单价表，设置=预算与峰谷提醒。
- * 导出供测试断言 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
- * accepts a bidirectional substring hit and a display-name alias list.
- * 导出供一致性守卫测试：catalog 每个厂商都必须在此登记（Custom 除外），
- * 防止新增厂商漏配导致健康绿灯不亮。
- */
-export declare const PROVIDER_ALIASES: Readonly<Record<string, readonly string[]>>;
-/**
- * 从真实 model id 反推提供方显示名：目录未收录的模型（key 落回「其他」）
- * 只靠 entry.provider（Custom）永远点不亮健康灯，这里用厂商别名对 model id
- * 做强匹配（别名作为完整 id / 前缀 / 独立段）与弱匹配（长别名子串），
- * 命中即显示厂商名并点亮健康点；无命中保持 Custom。
- * 导出供守卫测试：短别名（mi/yi）仅允许前缀形式，防止 minimax 等误吞。
- */
-export declare function providerFromModelKey(modelKey: string): string | undefined;
-/** 仅供测试：暴露厂商映射表（subscriptionVendorOf 仍是唯一消费入口）。 */
-export declare const SUBSCRIPTION_VENDORS_FOR_TEST: Readonly<Record<string, string>>;
-/**
- * 余额 provider → 官方充值页 URL。匹配顺序：归一化名精确/前缀命中 →
- * 经 PROVIDER_ALIASES 反查（余额 provider 名多为中文显示名，归一化仍是中文，
- * 需先命中 display 名再用其英文别名重试）。未收录返回 undefined。
- * 导出供测试：纯函数，不依赖组件。
- */
-export declare function rechargeUrlOf(provider: 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;
-/**
- * 用户自定义单价显示重估：聚合发生在宿主进程（按内置目录计价），用户价只在
- * 客户端显示层生效。对 byDayModels（day×model 完整二维）中命中用户价的模型
- * 逐格平价重算 cost，并派生 byDay / byModel / total 的 cost。其余视图
- * （bySite / byTier / bySession / byTurn）保持宿主原值——逐格时刻或行级归属
- * 在客户端不可得，口径差异在设置面板注明。导出供测试：纯函数。
- * @param stats - 服务端聚合文档。
- * @returns 重估后的文档；无用户价或缺 byDayModels 时原样返回。
- */
-export declare function recostWithUserPrices(stats: UsageStats): UsageStats;
-/**
- * 跨实例提醒认领后发系统通知（issue #44）：多实例（CLI + 桌面等）合法共存，
- * 各自轮询会重复弹通知。两级去重——进程内 Set 挡同进程的并发/重渲染（trigger
- * 与仪表盘是两个组件实例，effect 同周期并发时本地 store 标记读到的还是旧值）；
- * 跨进程走宿主认领端点（先到先得），另一实例刚发过则跳过。端点不可达（旧版本/
- * 网络故障）时放行，退化为原有 per-客户端去重。通知构造失败（平台限制）静默。
- * Set 导出供测试重置（模块级状态会跨用例泄漏）。
- */
-export declare const notifiedKeys: Set<string>;
-/** 近 7 天费用序列（含今天，缺日补 0）：触发卡 hover 速览的迷你柱数据源。
- * 导出供测试：纯函数（日期取本地时区）。 */
-export declare function activeDaysOf(byDay: Record<string, {
-    cost: number;
-}>): number;
-/** 连续使用天数：从今天往前连续「有调用记录」的天数；今天无记录则为 0。
- * 导出供测试：纯函数（日期取本地时区）。 */
-export declare function streakDaysOf(byDay: Record<string, {
-    cost: number;
-}>, now?: number): number;
-/** 按日 Token 口径：输入 + 输出。stats.input 本身已含缓存命中与未命中
- * （aggregate foldUsage：input = cacheHit + cacheMiss），再叠加缓存字段即重复
- * 计数——趋势图/热力图/触发卡/峰值日的按日 Token 一律走本函数（issue #85）；
- * 跨日合计在各行之上累加（KPI 见 kpiAgg，触发卡见 month/weekTokens）。
- * 导出供测试：纯函数。 */
-export declare function dayTokensOf(day: {
-    input: number;
-    output: number;
-}): number;
-/**
- * 近 7 天费用序列（含今天，缺日补 0）：触发卡 hover 速览的迷你柱数据源。
- * 导出供测试：纯函数（日期取本地时区）。
- * @param byDay - 按日费用表。
- * @returns 7 个 `{ date, cost }`，最旧在前。
- */
-export declare function lastSevenDays(byDay: Record<string, {
-    cost: number;
-}>): readonly {
-    date: string;
-    cost: number;
-}[];
-/**
- * 本自然周（周一起算）到 `today` 的累计值（issue #39）：标签「本周」的语义是
- * 自然周，近 7 天滚动窗口会在周一把上周用量卷进来（周一时它与当月几乎相等，
- * 用户误解为统计错误）。周一 = `getDay() === 1`；`pick` 决定日行取哪个维度。
- * @param byDay - 按日聚合表（key = `YYYY-MM-DD` 本地时区）。
- * @param today - 今天的本地日期戳。
- * @param pick - 日行取值（缺省取 cost；token 视角传 input+output 合计）。
- * @returns 本周一到今天的合计；`today` 本身不在表里（无调用）时为 0。
- */
-export declare function sinceMondayOf<T>(byDay: Record<string, T>, today: string, pick?: (row: T) => number): number;
-/** 平均成本的统计范围（issue #47）；`all` = 全量累计，不进逐日求和。 */
-export type AvgCostRange = 'today' | '7d' | 'week' | 'month' | 'all';
-/** 全局 KPI 按日聚合行的最小字段（byDay 行 = ModelUsage，结构兼容）。 */
-interface KpiDayRow {
-    cost: number;
-    calls: number;
-    input: number;
-    output: number;
-    cacheHit: number;
-    cacheMiss: number;
-    reasoning?: number;
-}
-/** 全局 KPI 聚合结果：KPI 七卡按所选范围重算所需的全部字段。 */
-export interface KpiAgg {
-    cost: number;
-    calls: number;
-    input: number;
-    output: number;
-    cacheHit: number;
-    cacheMiss: number;
-    reasoning: number;
-    /** 范围内总处理 Token（缓存读+缓存写+输出）最大的日期戳；窗口无数据时 undefined。 */
-    peakDay: string | undefined;
-    /** 峰值日的总处理 Token 量；窗口无数据时 0。 */
-    peakTokens: number;
-}
-/**
- * 按范围聚合 byDay（issue #47）：今日 / 近 7 天（含今天）/ 本周（周一起）/
- * 本月。日期戳字典序即时间序（与 dailyBurnRate 同口径）；累计口径由调用方
- * 直接取 total（含搜索估值兜底），不走此函数。
- */
-export declare function sumByDayRange(byDay: Record<string, KpiDayRow>, today: string, range: Exclude<AvgCostRange, 'all'>): KpiAgg;
-/** 会话明细行（与服务端 SessionUsageRow 同形；旧快照可能缺失整个 bySession）。 */
-interface SessionBillingRow {
-    id: string;
-    title?: string;
-    cwd?: string;
-    /**
-     * 直接父会话 id（仅子智能体会话携带）：宿主把子智能体落成独立会话，
-     * header 的 origin: subagent + parentSession 指向委派它的对话。
-     */
-    parentId?: string;
-    /** 全部后代子会话费用合计（服务端递归算好）；无后代时缺失。 */
-    subCost?: number;
-    /** 全部后代子会话调用数；无后代时缺失。 */
-    subCalls?: number;
-    /** 数据来自旧算法折叠的持久账本行（原始日志已删，无法重算）。 */
-    stale?: boolean;
-    calls: number;
-    cost: number;
-    lastActive: number;
-    /** 展示层合并标记（issue #42）：同标题会话归并后的段数（>1 时行尾显示 ×N）。 */
-    mergedCount?: number;
-    /** 合并组的段明细（展示层专用）：一级行默认收起，展开后逐段显示。合并函数需 push，故非 readonly。 */
-    children?: SessionBillingRow[];
-    /** 挂到本组下的子智能体行（展示层专用）：与段明细并列展开，带子智能体徽标。 */
-    subs?: SessionBillingRow[];
-}
-/** Usage stats structure from `.dsh-usage-stats.json`. */
-export interface UsageStats {
-    /** 服务端聚合时间戳（毫秒）；旧快照可能缺失。 */
-    updatedAt?: number;
-    /** 宿主进程时区（IANA 名 + UTC 偏移）：天按此切分，副标题据此标注；旧快照可能缺失。 */
-    timezone?: {
-        name: string;
-        offset: string;
-    };
-    /** 月度预算（人民币元）：宿主 Config 注入；未配置时不渲染预算条。 */
-    budget?: number;
-    /** 余额不足告警阈值（人民币元）：宿主 Config 注入；未配置时客户端用默认值。 */
-    lowBalanceThreshold?: number;
-    /** 会话明细（按费用倒序，服务端已封顶）；旧快照可能缺失。 */
-    bySession?: readonly SessionBillingRow[];
-    total: {
-        calls: number;
-        input: number;
-        output: number;
-        cacheHit: number;
-        cacheMiss: number;
-        /** 显式缓存写入（cacheMiss 子集，部分厂商单独报告）；1.0.8 起新增，旧快照缺失。 */
-        cacheWrite?: number;
-        cost: number;
-        /** 输出中的 reasoning（思考）token；已含在 output 内。 */
-        reasoning: number;
-        /** 联网搜索请求的估算调用数（已按次估值计入 cost）；1.0.9 起新增，旧快照缺失。 */
-        searchCalls?: number;
-    };
-    byModel: Record<string, {
-        calls: number;
-        input: number;
-        output: number;
-        cacheHit: number;
-        cacheMiss: number;
-        cost: number;
-        reasoning: number;
-        /** Billed through a subscription plan (no per-token cost). */
-        plan?: boolean;
-        /** 走官方 DeepSeek 直连的调用数（其余为第三方）；旧快照可能缺失。 */
-        officialCalls?: number;
-        /** 走官方渠道的费用（CNY）；旧快照可能缺失。 */
-        officialCost?: number;
-    }>;
-    byDay: Record<string, {
-        calls: number;
-        input: number;
-        output: number;
-        cacheHit: number;
-        cacheMiss: number;
-        cost: number;
-        reasoning: number;
-    }>;
-    /** 模型 × 日期 二维统计（趋势图堆叠柱的输入）；旧快照可能缺失，渲染时降级为单色柱。 */
-    byDayModels?: Record<string, Record<string, {
-        calls: number;
-        input: number;
-        output: number;
-        cacheHit: number;
-        cacheMiss: number;
-        cost: number;
-    }>>;
-    /** 模型 × 日期 × 站点 三维统计（[date][modelKey][siteKey]）：按 origin 绑定自定义价的
-     *  显示层重估数据源；旧快照可能缺失。 */
-    byDayModelsSite?: Record<string, Record<string, Record<string, {
-        calls: number;
-        input: number;
-        output: number;
-        cacheHit: number;
-        cacheMiss: number;
-        cost: number;
-        /** 该格全部调用都走订阅通道（聚合侧按三维格置位）；旧快照缺失，回退全局口径。 */
-        plan?: boolean;
-    }>>>;
-    /**
-     * 峰谷分桶（全量逐调用真实判档）：1.0.8 起服务端按调用时刻精确归桶，
-     * 峰谷占比条优先用它（覆盖全部历史调用）；旧快照缺失时回退逐轮估算。
-     */
-    byTier?: {
-        peak: {
-            cost: number;
-            calls: number;
-        };
-        offPeak: {
-            cost: number;
-            calls: number;
-        };
-    };
-    /** 工具调用次数排行（键 = 工具名，按次数倒序）；旧快照缺失。 */
-    byTool?: Record<string, number>;
-    /** 每轮费用明细（服务端聚合路径恒带）；旧快照可能缺失。 */
-    byTurn?: readonly {
-        sessionId: string;
-        turn: number;
-        model: string;
-        input: number;
-        output: number;
-        cacheHit: number;
-        cacheMiss: number;
-        cost: number;
-        startedAt: number;
-        endedAt?: number;
-    }[];
-    /** 工作区聚合（按 cwd 末级目录）；旧快照可能缺失。 */
-    byWorkspace?: readonly {
-        name: string;
-        calls: number;
-        cost: number;
-        input: number;
-        output: number;
-        lastActive: number;
-    }[];
-    /** 中转站归组（key = `site:<origin>` / `direct:<provider>` / `unknown`）；旧快照可能缺失。 */
-    bySite?: Record<string, {
-        calls: number;
-        input: number;
-        output: number;
-        cacheHit: number;
-        cacheMiss: number;
-        cost: number;
-        reasoning: number;
-    }>;
-    /** 不可计价模型 id（未收录/无价，费用按 0 计）；旧快照可能缺失。 */
-    unpricedModels?: readonly string[];
-    /** 联网搜索请求的单次费用估算（人民币元，配置回显）；0 或缺省 = 未启用估算。 */
-    searchCallEstimateCny?: number;
-    /** 按角色费用归因（估算口径：输出实测，输入按消息长度摊分）；旧快照可能缺失。 */
-    byRole?: {
-        user: number;
-        assistant: number;
-        tool: number;
-    };
-    /** 性能指标（TTFT/生成速度/总延迟）按模型与按小时；旧快照可能缺失。 */
-    perf?: ClientPerf;
-    /** 旧版算法账本行兜底的会话数（模型归属可能失真）；0 或缺省 = 全部数据可信。 */
-    staleLedgerSessions?: number;
-    /** 本轮未完整计入的会话数（跨轮次稳定）；0 或缺省 = 全部会话已统计。 */
-    unreadableSessions?: number;
-    /** 未统计中因会话格式拒读的子集（过新待宿主升级、过旧需迁移）；0 或缺省 = 无格式拒读。 */
-    unreadableFormatSessions?: number;
-    /** 未统计中无账本存档、完全未计入的子集；0 或缺省 = 拒读会话均有存档兜底。 */
-    unreadableNoLedgerSessions?: number;
-    /** 插件版本号（服务端读自包 package.json；旧快照缺失）。 */
-    pluginVersion?: string;
-}
-/**
- * 拉取官方余额差对账提示（drift 时非空），供余额面板展示；失败返回 undefined。
- * 复用 {@link fetchBalanceDoc} 的同一响应，导出供对账提示渲染测试单独解析。
- * @returns the reconcile notice, or undefined on any failure / no drift.
- */
-export declare function fetchReconcile(): Promise<ReconcileNotice | undefined>;
-/** 组件注入面：探活 + 计费指标写入（billing 自身写入，主题插件经服务读取）。 */
-export interface UsageBillingInjected {
-    checkModels: () => Promise<ModelHealth>;
-    publishCosts: (costs: {
-        todayCost: number;
-        monthCost: number;
-    }) => void;
-    registerOpen: (handler: () => void) => () => void;
-}
+import { NS } from './locales.ts';
+import { type UsageBillingInjected } from './domain/types.ts';
 /** 预算 store 的 props 份额（useStore 读取 + actions 写面）。 */
 type BillingBudgetStoreProps = PropsStore<ReturnType<typeof createBillingBudgetStore>>;
 /** Full props type for the UsageBilling component. */

package/lib/types/client/api/balance.d.ts

@@ -0,0 +1,24 @@
+/**
+ * GET /api/billing/balance：余额 + 对账提示（同一响应体）。30s 轮询单端点
+ * 比拆成两个端点更省（余额查询本身已有熔断与重试），失败回退空值。
+ */
+import type { ProviderBalance, ReconcileNotice } from '../../pricing-shared.ts';
+/** Path to the account-balance endpoint served by this plugin's node half. */
+export declare const BALANCE_PATH = "/api/billing/balance";
+/**
+ * 一次拉取 `/api/billing/balance` 的完整响应（余额行 + 对账提示）。余额与对账
+ * 提示来自同一响应体，拆成两个函数会导致每 30 秒对同一端点发两次请求，故合并
+ * 为单次 fetch；失败返回空值（余额 []、对账 undefined），由调用方降级。
+ * @returns the balances and reconcile notice (both degraded on any failure).
+ */
+export declare function fetchBalanceDoc(): Promise<{
+    balances: readonly ProviderBalance[];
+    reconcile?: ReconcileNotice;
+}>;
+/**
+ * 拉取官方余额差对账提示（drift 时非空），供余额面板展示；失败返回 undefined。
+ * 复用 {@link fetchBalanceDoc} 的同一响应，导出供对账提示渲染测试单独解析。
+ * @returns the reconcile notice, or undefined on any failure / no drift.
+ */
+export declare function fetchReconcile(): Promise<ReconcileNotice | undefined>;
+//# sourceMappingURL=balance.d.ts.map

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

@@ -0,0 +1,26 @@
+/**
+ * GET /api/billing/pricing + POST /api/billing/pricing/refresh：实时定价。
+ * 节点端启动时拉取，pricing source = 'builtin' 时本地内置（首次启动会回退
+ * 内置价）；重试链在收到完整 live 文档时立即结算。`livePricingRetryPending`
+ * 与 `lastPricingSyncedAt` 是模块级 let，**必须**与 `loadLivePricing` 同文件
+ * 保留（防止跨文件共享 mutable state；也是测试唯一可读的同步基线）。
+ */
+/** Path to the live-pricing endpoint served by this plugin's node half. */
+export declare const PRICING_PATH = "/api/billing/pricing";
+/** Path to the manual pricing-sync endpoint (POST) served by this plugin's node half. */
+export declare const PRICING_REFRESH_PATH = "/api/billing/pricing/refresh";
+/** 上次价格目录同步完成的本机时间戳（毫秒）：loadLivePricing 每次拿到完整
+ *  pricing 文档时更新；组件渲染时读取，手动同步后经 setState 触发重渲染刷新。
+ * `export let` 让 ESM live binding 暴露给外部——只读绑定（`import { x }` 在 ESM
+ * 中为只读），唯一写入点在本模块内 `lastPricingSyncedAt = ...`。 */
+export declare let lastPricingSyncedAt: number;
+declare function loadLivePricing(attempt?: number): Promise<void>;
+/**
+ * 手动同步价格目录：POST /api/billing/pricing/refresh 让服务端立刻重拉
+ * models.dev / 汇率，随后重载 pricing 文档并刷新界面。失败静默保持现状。
+ * @returns 同步是否成功（供按钮态展示降级）。
+ */
+export declare function syncPricingNow(): Promise<boolean>;
+/** 公开 loadLivePricing 供 UsageBilling 触发器/弹窗挂载时调用。 */
+export { loadLivePricing };
+//# sourceMappingURL=pricing.d.ts.map

package/lib/types/client/api/relay.d.ts

@@ -0,0 +1,13 @@
+/**
+ * GET /api/billing/relay-quotas：中转站额度（New API / Sub2API）。
+ * 失败抛出（调用方据此保留旧快照）。
+ */
+import type { RelayQuota } from '../../pricing-shared.ts';
+/** Path to the relay-site quota endpoint served by this plugin's node half. */
+export declare const RELAY_PATH = "/api/billing/relay-quotas";
+/**
+ * 拉取中转站额度（New API / Sub2API 的余额与滚动窗口）；失败抛出（调用方据此保留旧快照）。
+ * @returns the relay-site quota rows（成功但无中转配置时为空数组）。
+ */
+export declare function fetchRelayQuotas(): Promise<readonly RelayQuota[]>;
+//# sourceMappingURL=relay.d.ts.map

package/lib/types/client/api/subscriptions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * GET /api/billing/subscriptions：订阅套餐剩余额度（供订阅面板）。
+ * 失败抛出（调用方据此保留旧快照）。
+ */
+import type { SubscriptionQuota } from '../../pricing-shared.ts';
+/** Path to the subscription-plan quota endpoint served by this plugin's node half. */
+export declare const SUBSCRIPTIONS_PATH = "/api/billing/subscriptions";
+/**
+ * 拉取订阅套餐剩余额度（供订阅面板）；失败返回空列表。
+ * @returns the quota rows, or an empty list on any failure.
+ */
+export declare function fetchSubscriptions(): Promise<readonly SubscriptionQuota[]>;
+//# sourceMappingURL=subscriptions.d.ts.map

package/lib/types/client/api/usage-stats.d.ts

@@ -0,0 +1,11 @@
+/**
+ * GET /api/billing/usage-stats：服务端聚合文档（含 byDay/byModel/bySession/...）。
+ * 旧快照可能缺字段（聚合升级前落盘），解析时按字段白名单接受并兜底——避免
+ * 渲染路径读 undefined 抛错导致整个插件 surface 被卸载。
+ */
+import type { UsageStats } from '../domain/types.ts';
+/** Path to the usage-stats endpoint served by this plugin's node half. */
+export declare const USAGE_STATS_PATH = "/api/billing/usage-stats";
+/** Try to load stats from the server; returns null when no valid JSON stats are served. */
+export declare function loadUsageStats(): Promise<UsageStats | null>;
+//# sourceMappingURL=usage-stats.d.ts.map

package/lib/types/client/api/usage-tool.d.ts

@@ -0,0 +1,16 @@
+/**
+ * GET/POST /api/billing/usage-tool：usage_stats 工具开关读写（插件自带，
+ * 不依赖宿主浏览器设置白名单）。工具注入是启动期决策，重启应用后生效。
+ */
+/**
+ * 读取 usage_stats 工具开关当前值（插件自带接口，不依赖宿主浏览器设置白名单）。
+ * @returns 当前是否注入；读取失败（服务未起/非 JSON）返回 undefined。
+ */
+export declare function loadUsageTool(): Promise<boolean | undefined>;
+/**
+ * 写 usage_stats 工具开关（插件自带接口）。工具注入是启动期决策，重启应用后生效。
+ * @param enabled - 是否注入。
+ * @returns 是否写成功。
+ */
+export declare function saveUsageTool(enabled: boolean): Promise<boolean>;
+//# sourceMappingURL=usage-tool.d.ts.map

package/lib/types/client/budget-store.d.ts

@@ -18,6 +18,10 @@ export interface BudgetPrefsState {
     lastBalanceAlertDay: string;
     /** 最近一次峰谷切换提醒的切换点时刻（毫秒）：同一切换点只提醒一次。 */
     lastTierSwitchAt: number;
+    /** 按模型月度预算（模型目录键 → 人民币元/月；U-3）。缺键 = 该模型不限。 */
+    modelBudgets: Record<string, number>;
+    /** 按模型预算提醒的最后通知日期戳（`${model}:${tier}` → YYYY-MM-DD）：每模型每档每天最多一次。 */
+    modelTierAlertDays: Record<string, string>;
 }
 /** 预算偏好的完整写面（组件只能经这些 action 写入）；type 别名以兼容 ActionsDecl 的索引签名约束。 */
 export type BudgetPrefsActions = {
@@ -26,6 +30,8 @@ export type BudgetPrefsActions = {
     markTierAlerted: (d: BudgetPrefsState, tiers: readonly number[], day: string) => void;
     markBalanceAlerted: (d: BudgetPrefsState, day: string) => void;
     markTierSwitchAlerted: (d: BudgetPrefsState, at: number) => void;
+    setModelBudget: (d: BudgetPrefsState, key: string, value: number) => void;
+    markModelTierAlerted: (d: BudgetPrefsState, marks: readonly string[], day: string) => void;
 };
 /**
  * Declare the budget-preferences store handle.

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

@@ -0,0 +1,28 @@
+/**
+ * 客户端常量（无 React 依赖、无运行时副作用）：把 UsageBilling.tsx 散落的零散
+ * 常量集中到这里。UI 文案、key 名仍留在 locales.ts；这里只放「数值 / 路径 /
+ * 颜色 / 时间间隔」。
+ */
+import type { UsageStats } from './domain/types.ts';
+/** 预算提醒档位（百分比）：跨档时桌面通知，每档每天最多一次。 */
+export declare const BUDGET_ALERT_TIERS: readonly number[];
+/** 余额不足告警的默认阈值（人民币元）：宿主 Config 未配置时客户端兜底。 */
+export declare const DEFAULT_LOW_BALANCE_THRESHOLD = 50;
+/** 会话明细面板最多展示的行数（完整长尾在服务端另有一层封顶）。 */
+export declare const SESSION_DISPLAY_LIMIT = 20;
+/** 弹窗打开期间统计与定价的自动刷新间隔（毫秒）。 */
+export declare const STATS_REFRESH_INTERVAL_MS = 30000;
+/** 弹窗关闭后的统计刷新间隔（毫秒）：侧栏触发器只需大致最新值，降到 5 分钟
+ *  省宿主聚合（每轮都是折叠 + 五个端点的串行响应）。 */
+export declare const STATS_REFRESH_CLOSED_MS = 300000;
+/** Empty snapshot: shown before (or without) real host data — zeros, never fabricated samples. */
+export declare const EMPTY_STATS: UsageStats;
+/**
+ * 高区分度图表色板：趋势图柱、图例与计费表圆点按模型分配。不用模型品牌色
+ * （目录里多为蓝色系，视觉上几乎分不开），保证每个模型一眼可辨。
+ * 取设计 spec §3.4 七段色板（与 CSS --ds-c-1..7 同值；SVG presentation
+ * attribute 不解析 var()，故用同值字面量而非令牌引用），后三位保持
+ * 原有高区分度补位色，10 路循环不变。
+ */
+export declare const CHART_PALETTE: readonly string[];
+//# sourceMappingURL=constants.d.ts.map

package/lib/types/client/domain/forecast.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 本月预计 / 日均消耗（issue #47）：按日均外推本月总花费；余额可撑天数也复用。
+ * 纯函数（日期取本地时区），无 React 依赖。导出供测试。
+ */
+/**
+ * 日均消耗（元/天）：取最近 7 天（含今天）总花费 ÷ 有记录天数；无记录返回 0
+ * （此时可用天数无法估算，调用方不显示天数提示）。日期戳字典序即时间序。
+ */
+export declare function dailyBurnRate(byDay: Record<string, {
+    cost: number;
+}>, today: string): number;
+/**
+ * 本月预计总花费：按本月已有记录的平均日消耗 × 本月天数外推；无本月记录时
+ * 回退为最近 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;
+//# sourceMappingURL=forecast.d.ts.map

package/lib/types/client/domain/host-version.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 双宿主版本兼容：宿主 0.1.7 起把 IconChevronDownOutline14 拆为 Regular/Medium/Artwork
+ * 三个变体，旧名不再导出（issue #72：缺失名经宿主注入表解析为 undefined，渲染时
+ * 抛 React #130 并被 sidebar.footer.action 槽位错误边界弹出）。bundle 对 primitives
+ * 的 import 编译为运行时查表，缺失名不抛错，因此两个世代的名字都能同时引用：
+ * 0.1.6 宿主只有旧名，0.1.7+ 宿主只有新名，按宿主世代取用。Medium 的默认 size 为 14，
+ * 与旧组件渲染尺寸一致。导出名横跨两个宿主世代，单一类型版本无法同时声明，两个
+ * 名字都按记录类型断言取用（图标无 props 渲染，本地结构类型即可）。
+ *
+ * 抽到这里避免 BillingDashboard 的 prop 拖一份图标解析；与 primitives import 一同
+ * 隔离到独立文件，purify 走 tsdown 内联安全清单时更易管控。
+ */
+import type { ReactElement } from 'react';
+type BillingIcon = () => ReactElement | null;
+/** 运行时按宿主世代取用：0.1.7+ 走 Medium，旧名兜底。 */
+export declare const BillingChevronDown: BillingIcon | undefined;
+export {};
+//# sourceMappingURL=host-version.d.ts.map

package/lib/types/client/domain/icons.d.ts

@@ -0,0 +1,9 @@
+/**
+ * v1.5 Tab 内联 SVG 图标（14×14，无外部依赖；用 stroke="currentColor" 复用单 CSS 规则）。
+ * 抽到独立文件让 UsageBilling.tsx 体积下降；每个图标是 React.ReactNode，可被
+ * `<span aria-hidden>{icon}</span>` 包装嵌入。
+ */
+import type { ReactNode } from 'react';
+import type { DashboardTab } from './types.ts';
+export declare const TAB_ICONS: Record<DashboardTab, ReactNode>;
+//# sourceMappingURL=icons.d.ts.map

package/lib/types/client/domain/kpi.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 渲染层纯函数：健康点、订阅状态文本、订阅窗口标签、中转站程序类型、厂商组
+ * 费用合计、子智能体后代合计、本地时钟。这些函数都返回字符串/数字/CSS
+ * className，依赖 CSS module 提供的样式——抽到独立文件后 import 仍走
+ * `UsageBilling.module.css`。
+ */
+import type { ModelHealth, ModelRow, ProviderBillingGroup, RelayQuota, SessionBillingRow, SubscriptionQuota } from './types.ts';
+import type { UsageBillingKey } from '../locales.ts';
+/** Resolve one provider's dot state: green when live, red when failed, gray when unknown. */
+export declare function providerDot(health: ModelHealth, provider: string): string | undefined;
+/** 订阅额度查询状态的文案（ok 时无需额外标注，返回空串）。 */
+export declare function subscriptionStatusText(status: SubscriptionQuota['status'], t: (key: UsageBillingKey) => string): string;
+/** 订阅额度窗口的类型标签（本次 / 本周 / 本月 / 计费周期）。 */
+export declare function subscriptionWindowLabel(kind: SubscriptionQuota['windows'][number]['kind'], t: (key: UsageBillingKey) => string): string;
+/** 中转站程序类型的徽标文案（New API / Sub2API / 未识别）。 */
+export declare function relayKindText(kind: RelayQuota['kind'], t: (key: UsageBillingKey) => string): string;
+/** 中转站程序类型对应的样式类（复用站点类别配色）。 */
+export declare const RELAY_KIND_CLASS: Record<RelayQuota['kind'], string | undefined>;
+/**
+ * 厂商组费用合计（实际优先；订阅豁免行不计入）——付费者视角的一级信息（issue #34）。
+ * 订阅豁免行无 actual，其 estimated 是「按量等价」而非支出：计入组头会渲染出
+ * 「已豁免还要花钱」的误导（issue #37 的 grok 组头部 ¥383.6），预估语义保留在
+ * 模型行的订阅卡（「套餐内预估开销」）。
+ */
+export declare const providerCostOf: (group: ProviderBillingGroup) => number;
+/** 组行（单行或同标题合并组）的后代子智能体合计：合并组对成员段的 subCost/subCalls 求和。 */
+export declare function subFamilyOf(row: SessionBillingRow): {
+    cost: number;
+    calls: number;
+};
+export type { ModelRow };
+/** 本地时钟 `HH:MM:SS`：本仓时区展示用。 */
+export declare function formatClock(time: number): string;
+//# sourceMappingURL=kpi.d.ts.map

package/lib/types/client/domain/model-budget.d.ts

@@ -0,0 +1,13 @@
+/**
+ * U-3 按模型预算的纯函数：本月每模型消耗聚合与预算档位判定。
+ * 导出供测试。
+ */
+/** 本月每模型消耗：byDayModels（day×model）按月前缀归并 cost。 */
+export declare function monthCostByModel(byDayModels: Record<string, Record<string, {
+    cost: number;
+}>> | undefined, monthPrefix: string): Record<string, number>;
+/** 按模型预算档位（百分比）：与全局预算的 BUDGET_ALERT_TIERS 分档口径一致。 */
+export declare const MODEL_BUDGET_TIERS: readonly number[];
+/** 本月消耗跨过的档位列表（升序）；无预算或未跨档返回空。 */
+export declare function crossedModelBudgetTiers(cost: number, budget: number): readonly number[];
+//# sourceMappingURL=model-budget.d.ts.map