@kenz1117/dsh-ui-usage-billing 0.6.0 → 0.8.0

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

@@ -9,9 +9,15 @@
  * 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.
+ *
+ * The bar also carries two ambient signals: the current peak/off-peak pricing
+ * tier with a switch countdown (DeepSeek time-of-day pricing), and quota chips
+ * for subscription plans running low (≤20% remaining), so cost pressure is
+ * visible without opening the dashboard.
  */
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots';
 import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client';
+import type { UsageBillingKey } from './locales.ts';
 /** The usage-stats shape the composer bar needs (a thin slice, not the whole doc). */
 export interface LiveStats {
     bySession?: readonly {
@@ -24,6 +30,15 @@ export interface LiveStats {
         cost: number;
     }[];
 }
+/** 订阅额度的薄切片（/api/billing/subscriptions 响应的行）。 */
+export interface QuotaSlice {
+    displayName: string;
+    status: string;
+    windows: readonly {
+        kind: string;
+        remainingPercent: number;
+    }[];
+}
 /**
  * 当前会话累计费用：bySession 里会话 id 匹配的那行；缺省为 0。
  * 导出供测试：纯函数。
@@ -41,11 +56,22 @@ export declare function sessionCostOf(stats: LiveStats | null, sessionId: string
  * @returns 最新一轮费用（人民币元）。
  */
 export declare function turnCostOf(stats: LiveStats | null, sessionId: string | undefined): number;
+/**
+ * 低额度预警 chips：查询成功（ok）且任一窗口剩余 ≤ threshold 的套餐，
+ * 按剩余升序、最多 3 枚。导出供测试：纯函数。
+ * @param quotas - 订阅额度行切片。
+ * @param threshold - 剩余百分比阈值（默认 20%）。
+ */
+export declare function lowQuotaChips(quotas: readonly QuotaSlice[], threshold?: number): readonly {
+    name: string;
+    kind: string;
+    pct: 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;
+    t: (key: UsageBillingKey) => string;
 }
 /**
  * Render the live cost ticker for the current session.

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.trendEmpty' | 'billing.budget' | 'billing.sessions' | '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.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' | 'billing.export' | 'billing.exportCsvDay' | 'billing.exportCsvSession' | 'billing.exportJson' | 'billing.peakShare' | 'billing.peakShareHint' | 'billing.weekCost' | 'billing.roleCost' | 'billing.roleUser' | 'billing.roleAssistant' | 'billing.roleTool' | 'billing.roleHint';
+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.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.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.subscriptionExhausted' | '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' | '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.planTypeCode' | 'billing.planTypeToken' | 'billing.subscriptionFeePerMonth';
 export declare const NS = "usageBilling";
 export declare const zh: Record<UsageBillingKey, string>;
 export declare const en: Record<UsageBillingKey, string>;

package/lib/types/client/plan-knowledge.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Plan-knowledge reference (adapted from dsh-spend's `knowledge.js`, MIT):
+ * billing-plan shape (code = subscription, token = usage) for known providers,
+ * plus official token rates as a pricing fallback for providers whose models
+ * are not covered by the built-in catalog or models.dev.
+ *
+ * The cost model follows dsh-spend's dual-basis:
+ * - `code` plan (OpenCode Go, Coding/Token plans, etc.): the monthly cost is
+ *   the subscription fee, counted into the projected month total.
+ * - `token` plan (pay-as-you-go API providers): cost = tokens × unit price.
+ *
+ * We keep our own live-pricing path (models.dev + OpenRouter) for token plans;
+ * this table only fills the subscription amount, the plan type, and a fallback
+ * rate for the few models those live sources may miss.
+ */
+/** Plan type: code = subscription + quota, token = per-token usage. */
+export type PlanType = 'code' | 'token';
+/** One plan row: provider id (after alias) → plan shape + optional subscription fee. */
+export interface PlanKnowledgeEntry {
+    type: PlanType;
+    /** 订阅月费（人民币元）；code 计划用，计入「本月预计」。 */
+    subscriptionCny?: number;
+}
+/**
+ * 订阅/计划 provider id → plan 知识（引用 dsh-spend 的 code/token 双口径）。
+ * 覆盖我们实际会识别到的订阅通道；其余按量 API 不计入此表（默认 token）。
+ */
+export declare const PLAN_KNOWLEDGE: Readonly<Record<string, PlanKnowledgeEntry>>;
+/** provider id（llm-pi-ai 设置键）→ plan 知识；未命中默认 token。 */
+export declare function planTypeOf(providerId: string): PlanType;
+/** 订阅月费（人民币元）；非 code 或未配置时为 0。 */
+export declare function subscriptionCnyOf(providerId: string): number;
+export interface FallbackRate {
+    /** 归一化模型 id（计费键，与 catalogEntries 的 key 同口径）。 */
+    key: string;
+    input: number;
+    cacheHit: number;
+    output: number;
+}
+export declare const FALLBACK_RATES: readonly FallbackRate[];
+//# sourceMappingURL=plan-knowledge.d.ts.map

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

@@ -27,6 +27,22 @@ export declare const USD_TO_CNY = 6.79;
  * @param pricing - the `/api/billing/pricing` response.
  */
 export declare function applyLivePricing(pricing: LivePricing): void;
+/**
+ * 注入探活得到的「系统里实际配置/预制的模型」清单（host 的 llm.models 返回
+ * groups[].models[]，含模型 id/name，无价格）。费率表据此对标现实可用模型——
+ * 有价的补价（内置目录 / models.dev 补充），无价的标「未收录」。纯内存状态，
+ * 供 `catalogEntries()` 渲染。
+ */
+export declare function applyLiveCatalogModels(models: readonly CatalogModel[]): void;
+/** 探活模型清单条目（host 的 ModelCatalogModel 投影出需要的字段）。 */
+export interface CatalogModel {
+    /** 模型 id（如 `deepseek-v4-flash`）。 */
+    id: string;
+    /** 显示名；缺省用 id。 */
+    name?: string;
+    /** 厂商显示名（探活 group 名）。 */
+    provider: string;
+}
 /**
  * 当前生效的 USD → CNY 汇率及其来源：live = 启动时实时拉取成功，
  * builtin = 实时拉取失败、正在用内置默认值。
@@ -52,6 +68,30 @@ export declare function isPeakHour(beijingHour: number): boolean;
  * @param timeMs - Unix epoch 毫秒；null/undefined/NaN 视为未知。
  */
 export declare function tierAt(timeMs: number | null | undefined): PriceTierId;
+/**
+ * 当前峰谷档位与距下次切换的时长。导出供测试：纯函数。
+ * @param nowMs - 当前时刻（epoch 毫秒）。
+ * @returns 当前档位与到下一个切换边界的毫秒数。
+ */
+export declare function tierCountdown(nowMs: number): {
+    tier: PriceTierId;
+    nextSwitchInMs: number;
+};
+/**
+ * 峰/谷切换预告：距下次切换不足 leadMs 时返回即将进入的档位与切换时刻，
+ * 否则 null。导出供测试：纯函数。
+ * @param nowMs - 当前时刻（epoch 毫秒）。
+ * @param leadMs - 提前量（毫秒）。
+ */
+export declare function upcomingTierSwitch(nowMs: number, leadMs: number): {
+    entering: PriceTierId;
+    atMs: number;
+} | null;
+/**
+ * 切换倒计时短格式：`1h23m` / `45m` / `3m`。导出供测试：纯函数。
+ * @param ms - 剩余毫秒数。
+ */
+export declare function formatSwitchCountdown(ms: number): string;
 /** Usage buckets consumed by one model (counts in raw tokens). */
 export interface TokenUsageBuckets {
     /** Uncached input tokens. */
@@ -100,6 +140,8 @@ export interface ModelEntry {
      * 展示时标注以免误当正式定价；正式定价公布后移除。
      */
     estimated?: boolean;
+    /** 探活命中但无内置/models.dev 价：费率表标「未收录」，不参与计价。 */
+    uncatalogued?: boolean;
 }
 /**
  * Built-in catalog of current mainstream models as of 2026-08-16, priced from
@@ -126,6 +168,17 @@ export declare const MODEL_CATALOG: readonly ModelEntry[];
 export declare const MODEL_KEY_ALIASES: Readonly<Record<string, string>>;
 /** Lookup a model by its stats key; falls back to the generic `other` entry. */
 export declare function modelOf(key: string): ModelEntry;
+/**
+ * 模型是否可计价：内置目录、models.dev 补充、或 dsh-spend 官方价兜底命中。
+ * 聚合层的计价闸门（目录外模型不产生费用，避免兜底档误估）。
+ */
+export declare function isPriced(key: string): boolean;
+/**
+ * 费率表渲染的完整目录：内置 + models.dev 补充条目 + 探活模型（无价标记）。
+ * 探活模型去重（按归一化 id）：内置/补充已有的不再重复；无价的保留并标记
+ * `uncatalogued`，费率表据此显示「未收录」。
+ */
+export declare function catalogEntries(): readonly ModelEntry[];
 /** Resolve a price-table row by its CSS variable name (theme token or fallback color). */
 export declare function resolveToken(name: string): string;
 /**

package/lib/types/index.d.ts

@@ -12,7 +12,7 @@
 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 { SubscriptionPlanConfig } from './pricing-shared.ts';
+import type { CustomBalanceConfig, SubscriptionPlanConfig } from './pricing-shared.ts';
 import { type IdentifiedSubscriptionPlan, type SubscriptionKeys } from './subscriptions.ts';
 /** Plugin configuration. */
 export interface UsageBillingConfig {
@@ -29,6 +29,8 @@ export interface UsageBillingConfig {
     /** 余额不足告警阈值（人民币元）：余额低于此值时仪表盘每天提醒一次；
         不设置则客户端按默认阈值（50 元）兜底。 */
     lowBalanceThreshold?: number;
+    /** 自定义 Provider 余额查询（任意 HTTP 端点 + extract 规则，适配 NewApi/LiteLLM 等）。 */
+    customBalances?: readonly CustomBalanceConfig[];
 }
 /** Required services: the web server, the persisted session log store, and user settings. */
 export declare const inject: string[];

package/lib/types/plans.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 供应商计费计划知识库（对标 dsh-spend 的 PROVIDER_KNOWLEDGE / PROVIDER_ALIASES）。
+ *
+ * 每个 provider 归入两种计费口径之一：
+ * - `code`  —— 订阅制（coding / token / agent plan）：费用 = 订阅月费，额度按周期
+ *   计量，token 用量不计费（不按 token 扣钱）。
+ * - `token` —— 按量制：费用 = token × 单价（由 models.dev / OpenRouter / 内置目录
+ *   定价）。无知识库命中的 provider 默认按 token 口径。
+ *
+ * `aliasOf` 把部署里杂乱的 provider id（glm / kimi / dashscope…）归一化到知识库键，
+ * `planOf` 据此返回计费计划；日志出现的 provider 经此自动识别，无需人工配置。
+ */
+/** 计费口径：code = 订阅制（计月费），token = 按量制（计 token 单价）。 */
+export type BillingPlanKind = 'code' | 'token';
+/** 订阅月费的币种（只支持单一币种计费，与仪表盘币种一致）。 */
+export type BillingCurrency = 'CNY' | 'USD';
+/** 一个 provider 的计费计划。 */
+export interface BillingPlan {
+    /** 计费口径。 */
+    kind: BillingPlanKind;
+    /** 厂商显示名（未命中知识库时用 provider id 原样）。 */
+    label: string;
+    /** code 计划的订阅月费（单位 {@link currency}）；token 计划无此项。 */
+    subscriptionMonthly?: number;
+    /** 订阅月费币种。 */
+    currency?: BillingCurrency;
+    /** 订阅额度周期（天）；额度按此周期计量。 */
+    periodDays?: number;
+}
+/** 归一化 provider id 到知识库键；未命中的原样返回（避免误吞）。 */
+export declare function aliasOf(provider: string): string;
+/**
+ * 某 provider 的计费计划：命中的 code 计划返回订阅口径，`PROVIDER_LABELS` 命中的
+ * 按量厂商返回 token 口径（无月费）；完全未知返回 undefined（调用方按 token 兜底）。
+ */
+export declare function planOf(provider: string): BillingPlan | undefined;
+/** 是否已知为订阅制（code）provider。 */
+export declare function isCodePlan(provider: string): boolean;
+//# sourceMappingURL=plans.d.ts.map

package/lib/types/pricing-fetch.d.ts

@@ -7,7 +7,15 @@
  * half caches whatever succeeded and the browser dashboard falls back to the
  * catalog for the rest — a total outage answers `{ source: 'builtin' }`.
  */
-import type { LivePricing } from './pricing-shared.ts';
+import type { ExtraModelPrice, LivePricing } from './pricing-shared.ts';
+/**
+ * models.dev 响应 → 目录外补充条目。不再按厂商白名单过滤：凡是有有效
+ * cost 的模型都纳入（探活模型可能来自任何预制厂商，白名单会漏掉）。厂商
+ * 显示名优先取映射，未命中用 provider id。导出供测试：纯函数。
+ * @param data - `https://models.dev/api.json` 的响应体。
+ * @returns 补充条目（按 provider 顺序稳定；仅含可计价的模型）。
+ */
+export declare function buildExtraModels(data: unknown): ExtraModelPrice[];
 /**
  * Fetch the live pricing once at boot. Both upstreams run in parallel; a
  * failure in either degrades independently to the built-in value.

package/lib/types/pricing-shared.d.ts

@@ -21,6 +21,22 @@ export interface LivePricing {
     rate?: number;
     /** Overrides keyed by built-in catalog key (present when router matches succeeded). */
     prices?: Record<string, LivePrice>;
+    /**
+     * models.dev 补充的目录外模型价（USD / 1M tokens）：与宿主预制提供方对齐——
+     * pi-ai 预制目录的上游就是 models.dev，补进来的条目让「提供方支持但我们的
+     * 内置目录未收录」的模型也能计价并出现在费率表。
+     */
+    extraModels?: readonly ExtraModelPrice[];
+}
+/** models.dev 补充的目录外模型价（USD / 1M tokens）。 */
+export interface ExtraModelPrice {
+    /** 归一化模型 id（计费键，如 `deepseek-v4.5-flash`）。 */
+    key: string;
+    /** 显示名。 */
+    name: string;
+    /** 厂商显示名（与仪表盘厂商组同口径）。 */
+    provider: string;
+    price: LivePrice;
 }
 /** 余额查询失败的原因，前端据此显示文案。 */
 export type BalanceError = 'unconfigured' | 'unauthorized' | 'unreachable';
@@ -72,6 +88,14 @@ export interface SubscriptionQuota {
     status: SubscriptionStatus;
     /** Quota windows, newest-window first; empty when the query failed. */
     windows: readonly SubscriptionWindow[];
+    /**
+     * 计费计划类型（引用 dsh-spend 的双口径）：
+     * - `code` 订阅制：月度费用按订阅月费计入（dsh-spend 的 subscription）；
+     * - `token` 按量计费：按 token × 单价估算（dsh-spend 的 token plan）。
+     */
+    planType?: 'code' | 'token';
+    /** 订阅月费（人民币元；code 计划用，计入「本月预计」）。 */
+    subscriptionAmount?: number;
 }
 /** Response of `/api/billing/subscriptions`. */
 export interface SubscriptionResponse {
@@ -86,4 +110,38 @@ export interface SubscriptionPlanConfig {
     /** Z.ai region override; defaults to the settings-namespace `zaiRegion`. */
     region?: 'global' | 'bigmodel-cn';
 }
+/**
+ * 余额提取规则：从响应 JSON 取数。
+ * - `const`：数字常量；
+ * - `path`：点路径取值（如 `data.total_available`）；
+ * - `op: 'add' | 'subtract'` + `paths`：多路径加 / 减；
+ * - `op: 'divide'` + `path` + `by`：按除数缩放（适配 NewApi 等 quota 端点，
+ *   如 1 USD = 500000 quota）。
+ */
+export interface CustomBalanceExtract {
+    const?: number;
+    path?: string;
+    op?: 'add' | 'subtract' | 'divide';
+    paths?: readonly string[];
+    by?: number;
+}
+/** 一个自定义 Provider 余额查询配置（插件 config 的 `customBalances` 条目）。 */
+export interface CustomBalanceConfig {
+    /** 显示名（中文）。 */
+    label: string;
+    /** 显示名（英文）；缺省用 label。 */
+    labelEn?: string;
+    /** 余额币种（如 CNY / USD）；缺省 CNY。 */
+    unit?: string;
+    /** 查询端点（完整 URL）。 */
+    url: string;
+    /** HTTP 方法；缺省 GET。 */
+    method?: string;
+    /** 请求头；值支持 `{{ENV_NAME}}` 占位符，经凭据 seam 解析（仅请求头支持）。 */
+    headers?: Record<string, string>;
+    /** 余额提取规则。 */
+    extract: {
+        remaining: CustomBalanceExtract;
+    };
+}
 //# sourceMappingURL=pricing-shared.d.ts.map

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