@rayadesu/dsh-billing 0.1.0-rc.8

package/packages/llm-billing/tests/billing.spec.ts

@@ -0,0 +1,216 @@
+/**
+ * Session spend pricing: pricing resolution, peak-hour classification, and the
+ * per-session spend conversion. Pure functions only, so the suite is keyless
+ * and deterministic.
+ */
+import type { TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { describe, expect, it } from 'vitest'
+import {
+  computeSessionSpend,
+  computeTodaySpend,
+  isPeak,
+  resolveBilling,
+} from '../src/billing.ts'
+
+function assistantMessage(model: string, usage: TokenUsage, time = 0): SessionEvent {
+  return {
+    type: 'assistant/message',
+    seq: 0,
+    time,
+    data: {
+      turn: 0,
+      step: 0,
+      message: {
+        id: 'm' as never,
+        role: 'assistant',
+        content: [],
+        source: { kind: 'model', provider: 'deepseek-official', model },
+      },
+      usage,
+    },
+  } as unknown as SessionEvent
+}
+
+const FLASH = 'deepseek-v4-flash'
+const PRO = 'deepseek-v4-pro'
+const CATALOG = [
+  { id: FLASH, name: 'DeepSeek-V4-Flash' },
+  { id: PRO, name: 'DeepSeek-V4-Pro' },
+]
+
+describe('resolveBilling', () => {
+  it('uses the published defaults when no config is supplied', () => {
+    const billing = resolveBilling(undefined)
+    expect(billing.peakHours).toEqual([{ start: 9, end: 12 }, { start: 14, end: 18 }])
+    expect(billing.models.get(FLASH)?.peak).toEqual({ cacheHitInput: 0.10, cacheMissInput: 3.0, output: 9.0 })
+    expect(billing.models.get(PRO)?.offPeak).toEqual({ cacheHitInput: 0.15, cacheMissInput: 4.5, output: 13.5 })
+    // deepseek-v4-flash-vision-exp bills at the same published rates as flash.
+    expect(billing.models.get('deepseek-v4-flash-vision-exp')?.peak)
+      .toEqual({ cacheHitInput: 0.10, cacheMissInput: 3.0, output: 9.0 })
+    expect(billing.models.get('deepseek-v4-flash-vision-exp')?.offPeak)
+      .toEqual({ cacheHitInput: 0.05, cacheMissInput: 1.5, output: 4.5 })
+  })
+
+  it('overrides a model when an explicit row is supplied', () => {
+    const billing = resolveBilling({
+      models: [{
+        model: FLASH,
+        peak: { cacheHitInput: 1, cacheMissInput: 2, output: 3 },
+        offPeak: { cacheHitInput: 0.5, cacheMissInput: 1, output: 1.5 },
+      }],
+    })
+    expect(billing.models.get(FLASH)?.peak).toEqual({ cacheHitInput: 1, cacheMissInput: 2, output: 3 })
+    expect(billing.models.has(PRO)).toBe(false)
+  })
+
+  it('falls back to the defaults for empty arrays (schemastery materializes absent z.array as [])', () => {
+    const billing = resolveBilling({ models: [], peakHours: [] })
+    expect(billing.models.get(FLASH)?.peak).toEqual({ cacheHitInput: 0.10, cacheMissInput: 3.0, output: 9.0 })
+    expect(billing.models.get(PRO)?.offPeak).toEqual({ cacheHitInput: 0.15, cacheMissInput: 4.5, output: 13.5 })
+    expect(billing.peakHours).toEqual([{ start: 9, end: 12 }, { start: 14, end: 18 }])
+  })
+})
+
+describe('isPeak', () => {
+  it('classifies Beijing daytime hours as peak and others as off-peak', () => {
+    const billing = resolveBilling(undefined)
+    // 10:00 Beijing = 02:00 UTC; 20:00 Beijing = 12:00 UTC.
+    expect(isPeak(billing, new Date('2026-08-20T02:00:00Z'))).toBe(true)
+    expect(isPeak(billing, new Date('2026-08-20T12:00:00Z'))).toBe(false)
+  })
+})
+
+describe('computeSessionSpend', () => {
+  // 02:00Z is 10:00 Beijing (peak); 12:00Z is 20:00 Beijing (off-peak).
+  const PEAK = Date.parse('2026-08-20T02:00:00Z')
+  const OFF_PEAK = Date.parse('2026-08-20T12:00:00Z')
+  // Flash peak: hit 0.10, miss 3.0, output 9.0 CNY/M; off-peak: 0.05, 1.5, 4.5.
+  const USAGE: TokenUsage = { inputTokens: 1_000_000, outputTokens: 1_000_000, cacheReadTokens: 1_000_000, cacheWriteTokens: 500_000 }
+
+  it('prices cache hit, cache miss (including writes), and output at the peak rate for a peak-hour event', () => {
+    const spend = computeSessionSpend([assistantMessage(FLASH, USAGE, PEAK)], resolveBilling(undefined), CATALOG)
+    expect(spend.total).toBeCloseTo(0.10 + 4.50 + 9.00, 10)
+    expect(spend.models).toHaveLength(1)
+    const row = spend.models[0]
+    expect(row?.displayName).toBe('DeepSeek-V4-Flash')
+    expect(row?.cost).toBeCloseTo(13.60, 10)
+    expect(row?.peakCost).toBeCloseTo(13.60, 10)
+    expect(row?.offPeakCost).toBe(0)
+    expect(row?.cacheHitInputTokens).toBe(1_000_000)
+    expect(row?.cacheMissInputTokens).toBe(1_500_000)
+    expect(row?.outputTokens).toBe(1_000_000)
+    expect(row?.cacheHitInputCost).toBeCloseTo(0.10, 10)
+    expect(row?.cacheMissInputCost).toBeCloseTo(4.50, 10)
+    expect(row?.outputCost).toBeCloseTo(9.00, 10)
+  })
+
+  it('prices the same usage at the off-peak rate for an off-peak-hour event', () => {
+    const spend = computeSessionSpend([assistantMessage(FLASH, USAGE, OFF_PEAK)], resolveBilling(undefined), CATALOG)
+    expect(spend.total).toBeCloseTo(0.05 + 2.25 + 4.50, 10)
+    expect(spend.models[0]?.offPeakCost).toBeCloseTo(6.80, 10)
+    expect(spend.models[0]?.peakCost).toBe(0)
+    expect(spend.models[0]?.cacheHitInputCost).toBeCloseTo(0.05, 10)
+    expect(spend.models[0]?.cacheMissInputCost).toBeCloseTo(2.25, 10)
+    expect(spend.models[0]?.outputCost).toBeCloseTo(4.50, 10)
+  })
+
+  it('splits peak and off-peak portions across mixed-hour events', () => {
+    const spend = computeSessionSpend(
+      [assistantMessage(FLASH, USAGE, PEAK), assistantMessage(FLASH, USAGE, OFF_PEAK)],
+      resolveBilling(undefined),
+      CATALOG,
+    )
+    expect(spend.total).toBeCloseTo(13.60 + 6.80, 10)
+    expect(spend.models[0]?.peakCost).toBeCloseTo(13.60, 10)
+    expect(spend.models[0]?.offPeakCost).toBeCloseTo(6.80, 10)
+  })
+
+  it('omits a model that reported usage but has no pricing row', () => {
+    const spend = computeSessionSpend(
+      [assistantMessage('other-model', USAGE, PEAK)],
+      resolveBilling(undefined),
+      CATALOG,
+    )
+    expect(spend.total).toBe(0)
+    expect(spend.models).toEqual([])
+  })
+
+  it('returns a zero total for a session without billed usage', () => {
+    const spend = computeSessionSpend(
+      [{ type: 'turn/start', seq: 0, time: PEAK, data: { turn: 0 } }],
+      resolveBilling(undefined),
+      CATALOG,
+    )
+    expect(spend.total).toBe(0)
+    expect(spend.models).toEqual([])
+  })
+})
+
+describe('computeTodaySpend', () => {
+  // 2026-08-20 04:00Z is 2026-08-20 12:00 Beijing (off-peak; day 2026-08-20).
+  const NOW = Date.parse('2026-08-20T04:00:00Z')
+  // 02:00Z is 10:00 Beijing (peak), same Beijing day as NOW.
+  const PEAK = Date.parse('2026-08-20T02:00:00Z')
+  // 12:00Z is 20:00 Beijing (off-peak), same Beijing day as NOW.
+  const OFF_PEAK = Date.parse('2026-08-20T12:00:00Z')
+  // 16:30Z is 2026-08-21 00:30 Beijing — a different Beijing calendar day.
+  const NEXT_DAY = Date.parse('2026-08-20T16:30:00Z')
+  // 2026-08-19 20:00Z is 2026-08-20 04:00 Beijing — the previous UTC day but
+  // the same Beijing calendar day as NOW.
+  const PREVIOUS_UTC_DAY = Date.parse('2026-08-19T20:00:00Z')
+  const USAGE: TokenUsage = { inputTokens: 1_000_000, outputTokens: 1_000_000, cacheReadTokens: 1_000_000, cacheWriteTokens: 500_000 }
+
+  it('prices every priced event on the reference Beijing calendar day, from any session', () => {
+    const spend = computeTodaySpend(
+      [
+        assistantMessage(FLASH, USAGE, PEAK),
+        assistantMessage(FLASH, USAGE, OFF_PEAK),
+        assistantMessage(PRO, USAGE, PREVIOUS_UTC_DAY),
+      ],
+      resolveBilling(undefined),
+      CATALOG,
+      new Date(NOW),
+    )
+    // Flash peak 13.60 + Flash off-peak 6.80 + Pro off-peak 20.40.
+    expect(spend.total).toBeCloseTo(13.60 + 6.80 + 20.40, 10)
+    expect(spend.models).toHaveLength(2)
+    const flash = spend.models.find(row => row.model === FLASH)
+    expect(flash?.peakCost).toBeCloseTo(13.60, 10)
+    expect(flash?.offPeakCost).toBeCloseTo(6.80, 10)
+    const pro = spend.models.find(row => row.model === PRO)
+    expect(pro?.cost).toBeCloseTo(20.40, 10)
+  })
+
+  it('ignores events on other Beijing calendar days', () => {
+    const spend = computeTodaySpend(
+      [
+        assistantMessage(FLASH, USAGE, PEAK),
+        // 00:30 Beijing the next day — not today.
+        assistantMessage(FLASH, USAGE, NEXT_DAY),
+      ],
+      resolveBilling(undefined),
+      CATALOG,
+      new Date(NOW),
+    )
+    expect(spend.total).toBeCloseTo(13.60, 10)
+    expect(spend.models[0]?.cost).toBeCloseTo(13.60, 10)
+  })
+
+  it('returns a zero total when nothing priced falls on the reference day', () => {
+    const spend = computeTodaySpend(
+      [assistantMessage(FLASH, USAGE, NEXT_DAY)],
+      resolveBilling(undefined),
+      CATALOG,
+      new Date(NOW),
+    )
+    expect(spend.total).toBe(0)
+    expect(spend.models).toEqual([])
+  })
+
+  it('defaults the reference moment to now', () => {
+    const spend = computeTodaySpend([], resolveBilling(undefined), CATALOG)
+    expect(spend.total).toBe(0)
+    expect(spend.models).toEqual([])
+  })
+})

package/packages/llm-billing/tsconfig.json

@@ -0,0 +1,42 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../credentials/credentials"
+    },
+    {
+      "path": "../../util/launch-environment"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../session/session-persistence"
+    },
+    {
+      "path": "../../runtime-diagnostics/invariants"
+    },
+    {
+      "path": "../../typert/protocol"
+    }
+  ]
+}

package/packages/ui-billing/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record: the git blob hash of each side as of the
+# last confirmed-consistent state. Both languages carry equal authority; after
+# editing either side, bring the other along and re-record both hashes with:
+#   git hash-object README.md README.zh.md
+README.md: 509fb81169ba38ef35a3a364eb88765456143443
+README.zh.md: 19fa2ed3c3f4692c60945c614c44c5b832075100

package/packages/ui-billing/README.md

@@ -0,0 +1,30 @@
+# @rayadesu/dsh-client-ui-billing
+
+English | [中文](README.zh.md)
+
+Web billing feature owner: contributes one entry to `conversation.session.header.utilities` that mounts its own `billing` Remote, reads the DeepSeek account balance, this session's billed spend, and today's spend across every session through `billing/getBalance`, `billing/getSessionSpend`, and `billing/getTodaySpend`, and renders them as a top-right label box. The host half of the capability lives in [`dsh-llm-billing`](../llm-billing/README.md), which owns the `/user/balance` transport, the peak/off-peak pricing table, and the `billing` Remote namespace; this package mounts that Remote and renders what it returns.
+
+The trigger shows two lines — the remaining balance and this conversation's billed spend ("本轮对话花费 ¥X") — and renders nothing while the first fetch is in flight. Clicking it opens a label box with the remaining amount, this session's billed spend (本会话花费, priced per message at the official peak/off-peak rate) with today's all-session spend beside it (今日共花费), one priced row per model with the cache-hit / cache-miss-input / output cost breakdown ("缓存命中 ¥X · 未命中输入 ¥Y · 输出 ¥Z"), a manual refresh action, and a spend disclaimer. Refreshing keeps the last values visible rather than blanking them, and a refresh failure retains the last good value. A session or day without priced usage shows a "no usage recorded" word rather than a fabricated figure. A failure — no API key configured, a rejected credential, a transport error — renders a muted "Balance unavailable" word whose tooltip carries the Remote's own error message.
+
+The badge is account-level even though the slot is session-scoped: the header utilities row is simply the one always-visible title-bar seat the shell offers, and the balance it shows does not vary by session — but the spend lines do, because they price the current session's own token usage through `billing/getSessionSpend` and every session's usage through `billing/getTodaySpend`. Copy goes through the package's own `billing` locale namespace; styling uses tokens only.
+
+## Refresh mechanics
+
+The spends follow the conversation and the balance stays a manual snapshot:
+
+- **Spends follow new messages** — the component subscribes to the current session's message count through the framework `useSession` seat. When a new message lands, it recomputes this session's spend (`billing/getSessionSpend`) and today's spend (`billing/getTodaySpend`), local pricing passes with no network request, so the spend lines stay live during an ongoing conversation.
+- **Balance is manual** — the account balance is fetched on mount, on session switch, and on the explicit refresh action (`billing/getBalance`). There is no polling and no automatic refetch: the balance line only changes when one of those events happens.
+- **Refresh keeps the last values** — an in-flight refresh leaves the previous values on screen, and a failed refresh retains the last good value instead of blanking it.
+
+## Model Experience
+
+None, as this package renders account-level provider facts for a human and touches no prompt, message, schema, stream, or tool result. The model's own view of provider quota lives with the `QUOTA` / `INVALID_CREDENTIAL` error codes surfaced by [`dsh-llm`](https://github.com/deepseek-ai/deepseek-harness/tree/main/packages/llm/llm) on failed requests.
+
+#### KV Cache effect
+
+None; the package never assembles or sends provider requests, and its one RPC is a credential-authenticated account read that is not cached in the provider KV store.
+
+## Known Limitations and Deferred Work
+
+- **First balance line only** — the balance reads the primary (`balance_infos[0]`) currency line; other currency lines are not shown.
+- **Balance does not follow automatically** — the balance is a manual snapshot (no polling): spending from another client does not move the shown value until a refresh or browser reload.

package/packages/ui-billing/README.zh.md

@@ -0,0 +1,30 @@
+# @rayadesu/dsh-client-ui-billing
+
+[English](README.md) | 中文
+
+Web 额度特性的归属方：向 `conversation.session.header.utilities` 贡献一个条目，自己挂载 `billing` Remote，通过 `billing/getBalance`、`billing/getSessionSpend` 与 `billing/getTodaySpend` 读取 DeepSeek 账户余额、本会话的计费花费与今日所有会话的计费花费，并在右上角渲染成一个标签框。该能力的宿主侧在 [`dsh-llm-billing`](../llm-billing/README.md)，它拥有 `/user/balance` 传输、峰谷计价表与 `billing` Remote 命名空间；本包挂载那个 Remote 并渲染它返回的内容。
+
+触发器显示两行——剩余额度与本轮对话的计费花费（「本轮对话花费 ¥X」）——首个请求在途时不渲染任何东西。点击后展开一个标签框：剩余金额、本会话的计费花费（本会话花费，按官方峰/谷单价逐条消息计价，右侧并列今日所有会话的合计「今日共花费」）、每个模型一行的花费及其缓存命中/未命中输入/输出分项（「缓存命中 ¥X · 未命中输入 ¥Y · 输出 ¥Z」）、手动刷新按钮与花费说明。刷新时旧值不消失，刷新失败保留上一次有效值。没有可计价消耗的会话或日子显示「暂无消耗记录」而不是编造数字。失败——未配置 API key、凭据被拒绝、传输错误——渲染弱化的「额度不可用」，其提示携带 Remote 自己的错误信息。
+
+角标是账户级的，尽管插槽是会话作用域：顶栏工具行不过是外壳提供的那个始终可见的标题栏席位，余额并不随会话变化——但花费行会，因为它通过 `billing/getSessionSpend` 按当前会话自己的 token 用量计价、通过 `billing/getTodaySpend` 按所有会话的用量计价。文案走本包自己的 `billing` locale 命名空间；样式只用 token。
+
+## 数据更新机制
+
+花费跟随会话、额度保持手动快照：
+
+- **花费随新消息自动更新** —— 组件通过框架 `useSession` 座位订阅当前会话的消息数。每到达一条新消息，就只重算**本会话的花费**（`billing/getSessionSpend`）与**今日共花费**（`billing/getTodaySpend`，纯本地计价、不发网络请求），连续对话时花费行实时跟随。
+- **额度保持手动** —— 账户余额在挂载、切换会话、点刷新按钮时拉取（`billing/getBalance`）。**没有轮询、不会自动重拉**：余额行只在这几个时机变化。
+- **刷新保留旧值** —— 刷新在途时旧值留在屏幕上，刷新失败保留上一次有效值，不清空。
+
+## 模型体验
+
+无，因为本包为人类渲染账户级的 provider 事实，不触及 prompt、消息、schema、流或工具结果。模型对 provider 额度的视角仍在 [`dsh-llm`](https://github.com/deepseek-ai/deepseek-harness/tree/main/packages/llm/llm) 在请求失败时抛出的 `QUOTA` / `INVALID_CREDENTIAL` 错误码里。
+
+#### KV Cache effect
+
+无；本包从不组装或发送 provider 请求，它唯一的 RPC 是一次带凭据的账户读取，不落在 provider 的 KV 缓存里。
+
+## 已知限制与暂缓事项
+
+- **只取首条余额线** —— 余额读取主要（`balance_infos[0]`）币种行；其它币种行不显示。
+- **额度不自动跟随** —— 余额保持手动快照（无轮询）：其他客户端产生的消耗不会让界面数值自动变化，需手动刷新或刷新浏览器。