@cassius0924/dsh-usage-dashboard 0.3.1 → 0.5.0

package/lib/types/contract.d.ts

@@ -136,6 +136,56 @@ export interface SessionCost {
     /** Epoch ms of the last usage record in this session. */
     lastActive: number;
 }
+/**
+ * What the local log replay could actually inspect. Totals can otherwise look
+ * authoritative even when one corrupt session was skipped, so this metadata
+ * travels with every usage response and lets the UI disclose partial results.
+ */
+export interface UsageCoverage {
+    scope: 'local-dsh-session-logs';
+    /** Session headers with a usable id returned by the local persistence. */
+    listedSessions: number;
+    /** Session logs read successfully, including logs with no usage. */
+    scannedSessions: number;
+    /** Valid assistant usage records folded into the totals. */
+    usageRecords: number;
+    /** Usage records rejected because their time or token data was invalid. */
+    skippedRecords: number;
+    /** Session logs that could not be read at all. */
+    failedSessions: number;
+    /** Epoch ms of the first/last valid usage record across all local logs. */
+    earliestAt: number | null;
+    latestAt: number | null;
+}
+export declare const USAGE_WINDOW_DAYS: readonly [7, 30, 90, 365];
+export type UsageWindowDays = (typeof USAGE_WINDOW_DAYS)[number];
+/**
+ * Session ids observed in this codebase (host-issued, e.g.
+ * `session-484a1c14-c6fe-4d6a-abfd-a2d8d2f664d5`) are always plain
+ * ASCII-safe tokens — no documented format contract exists for them outside
+ * this repo (`SessionPersistenceFace`/`readFrom` is implemented by the DSH
+ * host, not here), so this is a defensive charset whitelist rather than an
+ * exact-format check: letters, digits, `-`, `_` only, with a generous length
+ * cap. It exists specifically to stop path-separator / `..` / null-byte
+ * payloads from ever reaching `persistence.readFrom(id, 0)` — `id` on the
+ * `/session` route arrives verbatim from the browser-controlled `?id=` query
+ * parameter, unlike `fetchUsage()`'s session ids, which the host itself
+ * enumerates via `persistence.list()`.
+ */
+export declare const SESSION_ID_PATTERN: RegExp;
+export declare const isValidSessionId: (id: string) => boolean;
+/** One internally consistent view of the same local logs over a calendar window. */
+export interface UsageWindow {
+    days: UsageWindowDays;
+    daily: DailyUsage[];
+    hourly: HourlyUsage[];
+    totals: UsageTotals;
+    models: ModelUsage[];
+    /** Most expensive sessions inside this window, capped at SESSION_TOP_N. */
+    sessions: SessionCost[];
+    /** All sessions that contributed usage inside this window. */
+    sessionCount: number;
+}
 export interface UsageData {
     daily: DailyUsage[];
     hourly: HourlyUsage[];
@@ -149,9 +199,63 @@ export interface UsageData {
     sessions: SessionCost[];
     /** How many sessions contributed usage in total. */
     sessionCount: number;
+    coverage: UsageCoverage;
+    windows: UsageWindow[];
 }
 export interface UsageResponse {
     ok: boolean;
     error?: string;
     data?: UsageData;
 }
+/**
+ * One model's contribution to a single session's bill — the same field
+ * shape as `ModelUsage` minus the `daily`/`hourly` series, which only make
+ * sense aggregated across many sessions.
+ */
+export interface SessionModelUsage {
+    provider: string;
+    model: string;
+    input: number;
+    output: number;
+    cache: number;
+    total: number;
+    cost: number;
+    calls: number;
+}
+/** One completed conversation turn's usage. `messageId` is the durable id of
+ * the turn's final assistant message — the same identity the chat action-strip
+ * slot exposes to client plugins. Tool-call steps inside the turn are folded
+ * into this one figure rather than shown as misleading separate charges. */
+export interface TurnUsage {
+    messageId: string;
+    total: number;
+    cost: number;
+    calls: number;
+}
+/**
+ * Usage for exactly one session — what the 「额度」tab's own conversation
+ * is costing, as opposed to `UsageData`'s account-wide totals. Fetched on
+ * demand (see `fetchSessionUsage`), not part of the 5-minute `usage` memo:
+ * a single session read is cheap and must reflect the session's live state.
+ */
+export interface SessionUsageData {
+    sessionId: string;
+    /** The session's own title from its log; falls back to a short id. */
+    title: string;
+    total: number;
+    cost: number;
+    calls: number;
+    /** Epoch ms of the first/last valid usage record in this session, or null
+     *  when the session has produced no usage yet. */
+    firstActive: number | null;
+    lastActive: number | null;
+    /** Most expensive model first. */
+    models: SessionModelUsage[];
+    /** Completed turns, in log order, addressed by their final message id. */
+    turns: TurnUsage[];
+}
+export interface SessionUsageResponse {
+    ok: boolean;
+    error?: string;
+    data?: SessionUsageData;
+}

package/lib/types/index.d.ts

@@ -2,12 +2,15 @@
  * dsh-usage-dashboard host plugin.
  *
  * Registers the package's own fenced JSON API under
- * `/api/dsh-usage-dashboard` (balance + usage), consumed by the client half
- * through same-origin fetch. Both endpoints are memoized with a TTL so that
- * tab switches and the widget's polling don't replay session logs or hammer
- * the DeepSeek API; responses carry `Cache-Control` so the browser's HTTP
- * cache serves repeat requests without a network round trip. `?refresh=1`
- * bypasses the memo for an explicit force refresh.
+ * `/api/dsh-usage-dashboard` (balance + usage + session), consumed by the
+ * client half through same-origin fetch. `balance` and `usage` are memoized
+ * with a TTL so that tab switches and the widget's polling don't replay
+ * session logs or hammer the DeepSeek API; responses carry `Cache-Control`
+ * so the browser's HTTP cache serves repeat requests without a network
+ * round trip. `?refresh=1` bypasses the memo for an explicit force refresh.
+ * `session` (usage for exactly one session, keyed by `?id=`) reads a single
+ * session log and is deliberately not memoized — it is cheap and must
+ * reflect that session's live state, not a 5-minute-stale snapshot.
  */
 import type { HostContext } from './context.ts';
 /** Plugin identity for the cordis.patch.yml row (and the client bundle id). */

package/lib/types/usage.d.ts

@@ -1,12 +1,12 @@
-/**
- * Balance and usage data sources.
- *
- * - Balance: DeepSeek API `GET /user/balance` with the key resolved through
- *   the credentials service (`DEEPSEEK_API_KEY`).
- * - Usage: token usage folded from the DSH session logs (`sessionPersistence`),
- *   one record per `assistant/message` event, bucketed by local day / hour.
- */
-import type { BalanceResponse, UsageResponse } from './contract.ts';
+import type { BalanceResponse, SessionUsageResponse, UsageResponse } from './contract.ts';
 import type { CredentialsFace, SessionPersistenceFace } from './context.ts';
 export declare function fetchBalance(credentials: CredentialsFace | undefined): Promise<BalanceResponse>;
-export declare function fetchUsage(persistence: SessionPersistenceFace | undefined): Promise<UsageResponse>;
+export declare function fetchUsage(persistence: SessionPersistenceFace | undefined, nowMs?: number): Promise<UsageResponse>;
+/**
+ * Usage for exactly one session — the 「额度」tab's own conversation, as
+ * opposed to `fetchUsage`'s account-wide replay. Reads a single session log
+ * (not every session on disk), so it is cheap enough to call on every tab
+ * mount without a TTL memo; the caller is expected to re-fetch whenever the
+ * session id it cares about changes.
+ */
+export declare function fetchSessionUsage(persistence: SessionPersistenceFace | undefined, sessionId: string): Promise<SessionUsageResponse>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassius0924/dsh-usage-dashboard",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "DeepSeek 额度与用量仪表盘 —— DSH (DeepSeek Harness) Web 插件：余额还能撑几天、今日/本月花了多少、哪个模型和哪个会话最贵、缓存省了多少，以及 2026-08-17 峰谷定价后的账单预估",
   "keywords": [
     "deepseek",
@@ -45,6 +45,7 @@
       "immediately": true,
       "inject": [
         "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
         "@deepseek-ai/dsh-client-ui-conversation"
       ]
     }
@@ -57,7 +58,8 @@
   ],
   "scripts": {
     "build": "node build.mjs",
-    "typecheck": "tsc --noEmit",
+    "test": "node test/run.mjs",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
     "prepare": "node build.mjs"
   },
   "license": "MIT",