@kenz1117/dsh-ui-usage-billing 0.1.0

package/lib/types/aggregate.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Real-usage aggregation: folds every persisted session log into the
+ * usage-stats document the dashboard renders.
+ *
+ * Each LLM call is attributed to the model of the `request/header` event that
+ * precedes its `assistant/message` usage event. Costs are estimated with the
+ * shared billing catalog (`pricing.ts`, in CNY), so only models the catalog
+ * prices incur a cost — subscription-plan routes and unknown models price
+ * zero while their tokens still count. Pure functions only: the persistence
+ * handle is injected, so the fold is unit-testable without a host.
+ */
+import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence';
+import type { TokenUsage } from '@deepseek-ai/dsh-llm';
+/**
+ * Real provider model ids map to their billing-catalog keys. Unknown ids stay
+ * as-is and price zero (they are not in the catalog; subscription-plan routes
+ * like kimi-coding / token plans fall here and therefore cost nothing).
+ */
+export declare const MODEL_KEY_ALIASES: Readonly<Record<string, string>>;
+/**
+ * 走订阅套餐（coding / token / agent plan）的 provider id：这些通道的调用
+ * 按套餐计费，不再按 token 计费，因此即使模型 id 与计费表撞名也一律豁免。
+ * 部署可在 plugin config 的 `subscriptionProviders` 中覆盖。
+ */
+export declare const DEFAULT_SUBSCRIPTION_PROVIDERS: readonly string[];
+/** Aggregation tuning options. */
+export interface AggregateOptions {
+    /** 订阅制 provider id 列表；默认 {@link DEFAULT_SUBSCRIPTION_PROVIDERS}。 */
+    subscriptionProviders?: readonly string[];
+}
+/** One model's aggregated usage plus estimated cost in CNY. */
+export interface ModelUsage {
+    calls: number;
+    input: number;
+    output: number;
+    cacheHit: number;
+    cacheMiss: number;
+    cost: number;
+}
+/** Zeroed usage accumulator. */
+export declare function emptyUsage(): ModelUsage;
+/**
+ * Fold one token usage event into an accumulator and re-price its cost.
+ * The stats `input` is the TOTAL prompt tokens (cacheHit + cacheMiss), so the
+ * miss bucket is uncached input plus cache writes.
+ * @param acc - the accumulator to mutate.
+ * @param usage - the provider-reported usage of one call.
+ * @param key - the billing-catalog key this call belongs to.
+ * @param subscription - whether the call went through a subscription plan; such calls never cost money.
+ */
+export declare function foldUsage(acc: ModelUsage, usage: TokenUsage, key: string, subscription: boolean): void;
+/** Local-time date stamp (the host runs in the user's timezone). */
+export declare function dayStamp(time: number): string;
+/**
+ * The persistence surface the aggregate reads: enough of
+ * `SessionPersistence` to list sessions and read each log once.
+ */
+export type UsagePersistence = Pick<SessionPersistence, 'list' | 'readFrom'>;
+/**
+ * Aggregate real usage from every persisted session log.
+ * @param persistence - the session persistence service.
+ * @param options - aggregation tuning (e.g. subscription-plan providers).
+ * @returns the usage-stats document (same shape the dashboard expects).
+ */
+export declare function aggregateUsage(persistence: UsagePersistence, options?: AggregateOptions): Promise<unknown>;
+//# sourceMappingURL=aggregate.d.ts.map

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

@@ -0,0 +1,22 @@
+/**
+ * TrendChart: dependency-free SVG combo chart of daily cost (area line) and
+ * daily call volume (bars) with a hover crosshair. No chart library — the
+ * surface stays self-contained and offline.
+ */
+/** One day row fed to the chart. */
+export interface TrendPoint {
+    /** ISO date `YYYY-MM-DD`. */
+    date: string;
+    /** USD cost that day. */
+    cost: number;
+    /** API calls that day. */
+    calls: number;
+}
+/**
+ * Render the daily trend chart.
+ * @param props.data - sorted daily rows (ascending date).
+ */
+export declare function TrendChart({ data }: {
+    data: readonly TrendPoint[];
+}): React.ReactNode;
+//# sourceMappingURL=TrendChart.d.ts.map

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

@@ -0,0 +1,40 @@
+/**
+ * UsageBilling: sidebar footer trigger + full billing dashboard modal.
+ *
+ * The trigger sits above Settings in the sidebar footer (rail shows an icon,
+ * wide shows a pill with the running total). Clicking opens a centered modal
+ * dashboard: hero total, KPI tiles, a dependency-free SVG daily trend chart,
+ * a per-model billing table priced from the built-in catalog, and a pricing
+ * 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.
+ */
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SidebarFooterActionOwnerProps } from '@deepseek-ai/dsh-client-ui-sidebar/client';
+import { NS } 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. */
+    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[];
+}
+/** Full props type for the UsageBilling component. */
+type UsageBillingProps = PropsRuntime<'sidebar.footer.action'> & SidebarFooterActionOwnerProps & InjectFace<{
+    checkModels: () => Promise<ModelHealth>;
+}> & PropsLocale<typeof NS>;
+/**
+ * UsageBilling: sidebar trigger plus the billing dashboard modal.
+ * @param props - framework-provided sidebar and locale props.
+ */
+export declare function UsageBilling(props: UsageBillingProps): React.ReactNode;
+export {};
+//# sourceMappingURL=UsageBilling.d.ts.map

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

@@ -0,0 +1,24 @@
+/**
+ * Usage billing plugin, browser half: registers the UsageBilling component
+ * in the sidebar.footer.action slot.
+ *
+ * Displays compact cost/token/cache metrics in the sidebar footer, above the
+ * Settings button, plus a model-health dot (green when any connected model
+ * route responds). Expands to a detailed dashboard panel on click.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import { type UsageBillingKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The usage billing surface's copy. */
+        usageBilling: UsageBillingKey;
+    }
+}
+/** Required services for the usage billing surface. */
+export declare const inject: string[];
+/**
+ * Client plugin body: the UsageBilling entry in the sidebar footer.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=apply.d.ts.map

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

@@ -0,0 +1,11 @@
+/**
+ * Usage billing surface plugin, browser half: compact cost/token metrics
+ * displayed in the session header utilities.
+ *
+ * Shows real-time cost, token usage, cache hit rate, and model breakdown.
+ * Expands to a detailed dashboard panel on click.
+ */
+export { inject, apply } from './apply.ts';
+export { UsageBilling } from './UsageBilling.tsx';
+export type { UsageBillingKey } from './locales.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,6 @@
+/** Locale dictionaries for the usage billing surface. */
+export type UsageBillingKey = 'billing.title' | 'billing.subtitle' | 'billing.cost' | 'billing.todayCost' | 'billing.totalCost' | 'billing.calls' | 'billing.cacheHitRate' | 'billing.tokens' | 'billing.inputTokens' | 'billing.outputTokens' | 'billing.avgCost' | 'billing.trend' | 'billing.trendEmpty' | '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';
+export declare const NS = "usageBilling";
+export declare const zh: Record<UsageBillingKey, string>;
+export declare const en: Record<UsageBillingKey, string>;
+//# sourceMappingURL=locales.d.ts.map

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

@@ -0,0 +1,118 @@
+/**
+ * Billing engine: per-model price tables and token-usage cost estimation.
+ *
+ * Each model's price table uses its NATIVE currency: domestic providers
+ * (DeepSeek, 智谱, 通义…) publish RMB prices and store them directly;
+ * overseas providers (OpenAI, Google, xAI, Meta) publish USD.
+ * Cost is always computed and displayed in CNY — only USD-priced models go
+ * through the exchange rate, never domestic ones.
+ *
+ * Google-style two-band billing is modeled per model: Gemini's Flex tier
+ * prices spare-capacity traffic at -50%; DeepSeek V4 splits peak
+ * (09:00-12:00 / 14:00-18:00 Beijing) at 2x the off-peak rate. The estimator
+ * mixes both bands by a configured peak share ({@link DEFAULT_PEAK_SHARE}).
+ */
+/**
+ * USD → CNY rate for display. Source: China Foreign Exchange Trade System
+ * mid-rate 6.7878 on 2026-08-14; rounded to 6.79. Only applies to overseas
+ * USD-priced models — domestic models never pass through this rate.
+ */
+export declare const USD_TO_CNY = 6.79;
+/** Default share of traffic assumed to fall in the peak band (0..1). */
+export declare const DEFAULT_PEAK_SHARE = 0.5;
+/**
+ * Model keys served through a subscription plan (e.g. a coding plan or topic
+ * plan) instead of metered per-token API billing. Usage through these routes
+ * costs no tokens: the estimator treats them as ¥0 and the billing table
+ * labels them 订阅包含. Add any model key your deployment serves through a
+ * plan here; leave empty when every route is pay-as-you-go.
+ */
+export declare const SUBSCRIPTION_PLAN_KEYS: readonly string[];
+/** Whether one stats model key is billed through a subscription plan. */
+export declare function isSubscriptionPlan(key: string): boolean;
+/** Usage buckets consumed by one model (counts in raw tokens). */
+export interface TokenUsageBuckets {
+    /** Uncached input tokens. */
+    input: number;
+    /** Cache-hit input tokens. */
+    cacheHit: number;
+    /** Cache-miss input tokens (already included in `input` by some providers). */
+    cacheMiss: number;
+    /** Output tokens. */
+    output: number;
+}
+/** Per-1M-token price in the model's native currency for one billing band. */
+export interface PriceBand {
+    /** Input (uncached) price per 1M tokens. */
+    input: number;
+    /** Cache-hit input price per 1M tokens. */
+    cacheHit: number;
+    /** Cache-miss input price per 1M tokens (absent when folded into `input`). */
+    cacheMiss?: number;
+    /** Output price per 1M tokens. */
+    output: number;
+}
+/** A model's price table, optionally split into peak/off-peak bands. */
+export interface ModelPrice extends PriceBand {
+    /** 计价币种：国内模型直接人民币（CNY），国外模型美元（USD）。 */
+    currency: 'CNY' | 'USD';
+    /** Off-peak band (Gemini Flex / DeepSeek 低谷档); absent = flat pricing. */
+    offPeak?: PriceBand;
+}
+/** One catalog entry: identity, brand color token, and price. */
+export interface ModelEntry {
+    /** Model key used by `.dsh-usage-stats.json` `byModel`. */
+    key: string;
+    /** Human-readable model name. */
+    name: string;
+    /** Provider label. */
+    provider: string;
+    /** CSS variable name (without the leading `--`) used as the brand accent. */
+    colorVar: string;
+    /** Price table (peak band when a split exists). */
+    price: ModelPrice;
+    /** Peak-hour window label for time-of-day priced models. */
+    peakHours?: string;
+}
+/**
+ * Built-in catalog of current mainstream models as of 2026-08-16, priced from
+ * each provider's official price page. Domestic providers are OpenAI-API
+ * compatible and publish RMB prices directly; overseas providers publish USD
+ * and convert through the exchange rate at estimate time. Retired models
+ * (GPT-4o family, Gemini 2.x, GLM-4.x-lite, older Qwen) are deliberately
+ * absent, as are Anthropic Claude models (their native API is not
+ * OpenAI-compatible, so the harness cannot drive them directly). DeepSeek
+ * keys match the harness stats file so real usage prices from the catalog;
+ * unknown keys fall back to `other`.
+ *
+ * Time-of-day billing (peak/off-peak) is now real: DeepSeek V4 officially
+ * splits peak (09:00-12:00 / 14:00-18:00 Beijing) at 2x the off-peak rate
+ * from 2026-08-17, and Gemini's Flex tier discounts spare-capacity traffic.
+ */
+export declare const MODEL_CATALOG: readonly ModelEntry[];
+/** Lookup a model by its stats key; falls back to the generic `other` entry. */
+export declare function modelOf(key: string): ModelEntry;
+/** Resolve a price-table row by its CSS variable name (theme token or fallback color). */
+export declare function resolveToken(name: string): string;
+/**
+ * Estimate the CNY cost of one model's token usage, mixing the peak and
+ * off-peak bands by the given peak share (flat-priced models cost the same in
+ * both bands).
+ * @param entry - the catalog entry whose prices apply.
+ * @param buckets - token usage counts.
+ * @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;
+/** Format a CNY amount with adaptive precision. */
+export declare function formatMoney(cny: number): string;
+/**
+ * Format a per-1M-token price in its native currency (free when the rate is
+ * zero): CNY for domestic models, USD for overseas ones.
+ */
+export declare function formatUnitPrice(price: number, currency?: 'CNY' | 'USD'): string;
+/** Format a large token count with B/M/K suffix. */
+export declare function formatTokens(value: number): string;
+/** Format a percentage. */
+export declare function formatPercent(value: number): string;
+//# sourceMappingURL=pricing.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Usage billing surface plugin, node half.
+ *
+ * Serves `/api/billing/usage-stats`: real usage aggregated from every
+ * persisted session log (see `aggregate.ts`) — the browser dashboard reads it
+ * instead of showing an empty snapshot. When `sessionPersistence` is
+ * unavailable (or aggregation fails), the configured `statsPath` /
+ * `DSH_USAGE_STATS` / conventional JSON file is served as a fallback, and a
+ * missing file answers `{ error }` so the dashboard shows zeros, never
+ * fabricated samples.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Plugin configuration. */
+export interface UsageBillingConfig {
+    /** Absolute path to a `.dsh-usage-stats.json` fallback file. */
+    statsPath?: string;
+    /** 订阅制（coding / token / agent plan）provider id 列表；默认 kimi-coding、xiaomi-token-plan-cn。 */
+    subscriptionProviders?: string[];
+}
+/** Required services: the web server and the persisted session log store. */
+export declare const inject: string[];
+/**
+ * Host plugin body: serve real aggregated usage to the browser dashboard.
+ * @param ctx - host context carrying webServer and sessionPersistence.
+ * @param config - optional statsPath override.
+ */
+export declare function apply(ctx: Context, config?: UsageBillingConfig): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,11 @@
+/** Package invariant companion for `@kenz1117/dsh-ui-usage-billing`. */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "usage-billing-invariant";
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Host context carrying the invariant registry.
+ * @returns the registration disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,86 @@
+{
+  "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.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kenz1117/dsh-ui-usage-billing.git"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-api-remotes": "*",
+    "@deepseek-ai/dsh-client-connection": "*",
+    "@deepseek-ai/dsh-host-webserver": "*",
+    "@deepseek-ai/dsh-client-locale": "*",
+    "@deepseek-ai/dsh-client-runtime": "*",
+    "@deepseek-ai/dsh-client-ui-conversation": "*",
+    "@deepseek-ai/dsh-client-ui-sidebar": "*",
+    "@deepseek-ai/dsh-client-ui-primitives": "*",
+    "@deepseek-ai/dsh-client-ui-slots": "*",
+    "@deepseek-ai/dsh-invariants": "*",
+    "@deepseek-ai/dsh-llm": "*",
+    "@deepseek-ai/dsh-session": "*",
+    "@deepseek-ai/dsh-session-persistence": "*",
+    "@deepseek-ai/cordis": "*",
+    "react": "^18.2.0"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-locale": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "~18.3.1",
+    "@deepseek-ai/cordis": "workspace:^",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ]
+}