@rayadesu/dsh-billing 0.1.0-rc.8

package/packages/ui-billing/src/client/BalanceBadge.tsx

@@ -0,0 +1,266 @@
+/** Session-header billing badge: balance plus the current conversation's billed spend. */
+
+import { Fragment, useEffect, useRef, useState } from 'react'
+import type { DeepSeekBalance, DeepSeekSessionSpend, DeepSeekTodaySpend } from '@rayadesu/dsh-llm-billing/types'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import { IconChevronDownOutline14, IconQuestionOutline14, IconRefreshOutline14, Tooltip } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { NS } from './locales.ts'
+import css from './BalanceBadge.module.css'
+
+/** Registration-side Remote face used by the header badge. */
+export interface BalanceBadgeInjected {
+  /** Read the account balance; rejects with the Remote error message. */
+  getBalance: () => Promise<DeepSeekBalance>
+  /** Read one session's billed spend; rejects with the Remote error message. */
+  getSessionSpend: (sessionId: SessionId) => Promise<DeepSeekSessionSpend>
+  /** Read today's billed spend across every session; rejects with the Remote error message. */
+  getTodaySpend: () => Promise<DeepSeekTodaySpend>
+}
+
+/** Full props assembled by the header utilities slot renderer. */
+export type BalanceBadgeProps =
+  PropsRuntime<'conversation.session.header.utilities'>
+  & InjectFace<BalanceBadgeInjected>
+  & PropsLocale<typeof NS>
+
+/** Currency prefix for one balance line; unknown codes render as a literal prefix. */
+function currencySymbol(currency: string): string {
+  if (currency === 'CNY') return '¥'
+  if (currency === 'USD') return '$'
+  return `${currency} `
+}
+
+/** The primary balance line, or undefined when the provider reports none. */
+function primaryLine(balance: DeepSeekBalance): { symbol: string; total: string } | undefined {
+  const line = balance.lines[0]
+  if (line === undefined) return undefined
+  return { symbol: currencySymbol(line.currency), total: line.total }
+}
+
+/** CNY amount, up to four decimals with trailing zeros trimmed. */
+function formatSpend(amount: number): string {
+  return `¥${amount.toFixed(4).replace(/\.?0+$/, '')}`
+}
+
+/**
+ * Render the billing badge in the session-header utilities row. The trigger
+ * shows the remaining balance and this conversation's billed spend and opens
+ * a label box with the amount, this session's spend with its cache-hit /
+ * cache-miss-input / output cost breakdown per model, today's spend across
+ * every session, a refresh action, and a spend disclaimer. Refreshing keeps
+ * the last values visible rather than blanking them.
+ *
+ * The spend follows the conversation: a new message in the current session
+ * recomputes only the (local, network-free) session spend and today's spend
+ * through `getSessionSpend` / `getTodaySpend`; the balance stays a
+ * manual-refresh snapshot and is never refetched on its own.
+ * @param props - Remote face, locale, and the standard session-header runtime share.
+ * @returns the badge, or null until the first balance fetch settles.
+ */
+export function BalanceBadge({ getBalance, getSessionSpend, getTodaySpend, sessionId, useSession, t }: BalanceBadgeProps) {
+  const [balance, setBalance] = useState<DeepSeekBalance | null>(null)
+  const [spend, setSpend] = useState<DeepSeekSessionSpend | null>(null)
+  const [todaySpend, setTodaySpend] = useState<DeepSeekTodaySpend | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [refreshing, setRefreshing] = useState(false)
+  const [open, setOpen] = useState(false)
+  const [request, setRequest] = useState(0)
+  const rootRef = useRef<HTMLDivElement>(null)
+
+  // The in-window message count is the "new message" signal: it changes when a
+  // message lands in the current session, letting the spend-only effect below
+  // react without touching the account balance.
+  const messageCount = useSession(snapshot => snapshot.chat.order.length)
+
+  // The last message count this component already priced, so the spend-only
+  // effect skips the initial mount (the mount effect already fetched).
+  const pricedMessageCountRef = useRef(messageCount)
+
+  useEffect(() => {
+    let current = true
+    // A refresh (values already present) keeps the previous values on screen;
+    // the first load has nothing to keep, so it stays on the loading render.
+    setRefreshing(balance !== null)
+    void Promise.resolve().then(() => {
+      // Each line settles on its own: the badge renders from the balance and
+      // the panel rows from their own spend, so a slow aggregate (today's
+      // spend scans every session) delays neither the balance nor the session
+      // spend.
+      const balanceRequest = Promise.resolve().then(getBalance).then(
+        (value) => {
+          if (!current) return
+          setBalance(value)
+          setError(null)
+        },
+        (reason: unknown) => {
+          if (!current) return
+          // A refresh failure keeps the last good value instead of blanking it.
+          if (balance === null) setError(reason instanceof Error ? reason.message : String(reason))
+        },
+      )
+      const sessionSpendRequest = Promise.resolve().then(() => getSessionSpend(sessionId)).then(
+        (value) => {
+          if (!current) return
+          setSpend(value)
+        },
+        () => {
+          // A failed refetch keeps the last good value instead of blanking it.
+        },
+      )
+      const todaySpendRequest = Promise.resolve().then(getTodaySpend).then(
+        (value) => {
+          if (!current) return
+          setTodaySpend(value)
+        },
+        () => {
+          // A failed refetch keeps the last good value instead of blanking it.
+        },
+      )
+      // The refresh spinner covers the whole refresh, whatever settles last.
+      void Promise.allSettled([balanceRequest, sessionSpendRequest, todaySpendRequest]).then(() => {
+        if (current) setRefreshing(false)
+      })
+    })
+    return () => { current = false }
+  }, [getBalance, getSessionSpend, getTodaySpend, sessionId, request])
+
+  // A new message lands: recompute this session's spend and today's spend
+  // across every session. The balance is account-level and stays a manual
+  // snapshot — never refetched here.
+  useEffect(() => {
+    if (messageCount === pricedMessageCountRef.current) return
+    pricedMessageCountRef.current = messageCount
+    let current = true
+    void Promise.resolve().then(() => {
+      // Each spend line updates on its own: the slow all-session aggregate
+      // does not delay the session line.
+      void Promise.resolve().then(() => getSessionSpend(sessionId)).then(
+        (value) => {
+          if (!current) return
+          setSpend(value)
+        },
+        () => {
+          // A failed recompute keeps the last good value.
+        },
+      )
+      void Promise.resolve().then(getTodaySpend).then(
+        (value) => {
+          if (!current) return
+          setTodaySpend(value)
+        },
+        () => {
+          // A failed recompute keeps the last good value.
+        },
+      )
+    })
+    return () => { current = false }
+  }, [getSessionSpend, getTodaySpend, sessionId, messageCount])
+
+  // A pointer press outside the label box closes it.
+  useEffect(() => {
+    if (!open) return
+    const closeOutside = (event: PointerEvent): void => {
+      if (event.target instanceof Node && !rootRef.current?.contains(event.target)) setOpen(false)
+    }
+    document.addEventListener('pointerdown', closeOutside)
+    return () => { document.removeEventListener('pointerdown', closeOutside) }
+  }, [open])
+
+  if (balance === null) {
+    if (error === null) return null
+    return (
+      <Tooltip label={error} delayMs={500}>
+        <button type="button" className={css.trigger} onClick={() => { setRequest(value => value + 1) }} aria-label={t('action.refresh')}>
+          <span className={css.unavailable}>{t('state.unavailable')}</span>
+          <IconRefreshOutline14 className={css.inlineIcon} />
+        </button>
+      </Tooltip>
+    )
+  }
+
+  const refresh = (): void => { setRequest(value => value + 1) }
+
+  const line = primaryLine(balance)
+  const amount = line === undefined ? '—' : `${line.symbol}${line.total}`
+  const spendLine = spend !== null && spend.models.length > 0
+    ? t('trigger.conversationSpend', { amount: formatSpend(spend.total) })
+    : undefined
+
+  return (
+    <div ref={rootRef} className={css.root}>
+      <button
+        type="button"
+        className={css.trigger}
+        aria-expanded={open}
+        aria-label={t('badge.aria', { amount })}
+        onClick={() => { setOpen(value => !value) }}
+      >
+        <span className={css.triggerLines}>
+          <span className={css.linePrimary}>{t('trigger.balance', { amount })}</span>
+          {spendLine !== undefined && <span className={css.lineSecondary}>{spendLine}</span>}
+        </span>
+        <IconChevronDownOutline14 className={open ? css.chevronOpen : undefined} />
+      </button>
+      {open
+        ? (
+          <div className={css.panel} role="dialog" aria-label={t('panel.aria')}>
+            <div className={css.amountRow}>
+              <span className={css.amountLabel}>{t('label.amount', { amount })}</span>
+              <span className={css.amountActions}>
+                <Tooltip label={t('info.hint')} delayMs={200} maxWidth={340}>
+                  <button type="button" className={css.infoButton} aria-label={t('info.aria')}>
+                    <IconQuestionOutline14 className={css.inlineIcon} />
+                  </button>
+                </Tooltip>
+                <button
+                  type="button"
+                  className={css.refreshButton}
+                  onClick={refresh}
+                  aria-label={t('action.refresh')}
+                  data-refreshing={refreshing || undefined}
+                >
+                  <IconRefreshOutline14 className={refreshing ? css.spinning : css.inlineIcon} />
+                </button>
+              </span>
+            </div>
+            <div className={css.spendRow}>
+              <span className={css.amountLabel}>{t('label.sessionSpend', {
+                amount: spend === null
+                  ? '—'
+                  : spend.models.length === 0
+                    ? t('stat.none')
+                    : formatSpend(spend.total),
+              })}</span>
+              <span className={css.amountLabel}>{t('label.todaySpend', {
+                amount: todaySpend === null
+                  ? '—'
+                  : todaySpend.models.length === 0
+                    ? t('stat.none')
+                    : formatSpend(todaySpend.total),
+              })}</span>
+            </div>
+            {spend?.models.map(model => (
+              <Fragment key={model.model}>
+                <div className={css.modelRow}>
+                  <span className={css.modelName}>{model.displayName}</span>
+                  <span className={css.tasks}>{formatSpend(model.cost)}</span>
+                </div>
+                <div className={css.costRow}>
+                  <span className={css.costBreakdown}>
+                    {t('label.cost.hit', { amount: formatSpend(model.cacheHitInputCost) })}
+                    {' · '}
+                    {t('label.cost.input', { amount: formatSpend(model.cacheMissInputCost) })}
+                    {' · '}
+                    {t('label.cost.output', { amount: formatSpend(model.outputCost) })}
+                  </span>
+                </div>
+              </Fragment>
+            ))}
+          </div>
+        )
+        : null}
+    </div>
+  )
+}

package/packages/ui-billing/src/client/index.ts

@@ -0,0 +1,80 @@
+/** DeepSeek account-balance badge, browser half: one session-header utility entry. */
+
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import billingRemote from '@rayadesu/dsh-llm-billing/remote'
+import type {} from '@rayadesu/dsh-llm-billing/remote'
+import type { TypertRemoteNamespaceMap } from '@deepseek-ai/dsh-typert-protocol'
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { BalanceBadge, type BalanceBadgeInjected } from './BalanceBadge.tsx'
+import { en, NS, zh, type BillingKey } from './locales.ts'
+
+export type { BalanceBadgeInjected, BalanceBadgeProps } from './BalanceBadge.tsx'
+export type { BillingKey } from './locales.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    /** DeepSeek account-balance copy. */
+    'billing': BillingKey
+  }
+}
+
+/** Services required for locale registration, the Remote face, and the header slot. */
+export const inject = ['slots', 'locale', 'remote']
+
+/** The mounted `billing` namespace surface, selected from the generated Remote map. */
+type BillingNamespace = TypertRemoteNamespaceMap['billing']
+
+/**
+ * Client plugin body: mount the `billing` Remote, register the dictionaries,
+ * and contribute the header utility badge.
+ * @param ctx - client root context.
+ */
+export async function apply(ctx: ClientContext): Promise<void> {
+  // Mount the Remote owned by this plugin; the host half is `dsh-llm-billing`.
+  await ctx.remote.$mount(billingRemote)
+  // The mounted namespace is read through the explicit service lookup. The
+  // property access `ctx.remote.billing` would require `remote.billing` in this
+  // fiber's inject list, which deadlocks: this apply mounts that namespace, so
+  // it cannot also wait for it before running.
+  const billing = ctx.get('remote.billing') as BillingNamespace | undefined
+  if (billing === undefined) {
+    throw new Error('ui-billing: billing Remote namespace did not mount')
+  }
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-billing: dictionaries')
+
+  const injected = (): BalanceBadgeInjected => ({
+    getBalance: async () => {
+      const result = await billing.getBalance()
+      if (!result.ok) {
+        throw new Error(`billing.getBalance failed: ${result.error.code}: ${result.error.message}`)
+      }
+      return result.value
+    },
+    getSessionSpend: async (sessionId) => {
+      const result = await billing.getSessionSpend(sessionId)
+      if (!result.ok) {
+        throw new Error(`billing.getSessionSpend failed: ${result.error.code}: ${result.error.message}`)
+      }
+      return result.value
+    },
+    getTodaySpend: async () => {
+      const result = await billing.getTodaySpend()
+      if (!result.ok) {
+        throw new Error(`billing.getTodaySpend failed: ${result.error.code}: ${result.error.message}`)
+      }
+      return result.value
+    },
+  })
+
+  ctx.slots.inject(
+    'conversation.session.header.utilities',
+    () => ctx.slots.register({
+      name: 'conversation.session.header.utilities',
+      id: 'billing-balance',
+      order: 30,
+      locale: NS,
+      inject: injected,
+    }, BalanceBadge),
+  )
+}

package/packages/ui-billing/src/client/locales.ts

@@ -0,0 +1,45 @@
+/** `billing` namespace dictionaries. */
+
+/** Dictionary namespace owned by this plugin. */
+export const NS = 'billing'
+
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export const zh = {
+  'trigger.balance': '剩余额度：{amount}',
+  'trigger.conversationSpend': '本轮对话花费：{amount}',
+  'label.amount': 'API 剩余金额：{amount}',
+  'label.sessionSpend': '本会话花费：{amount}',
+  'label.todaySpend': '今日共花费：{amount}',
+  'label.cost.hit': '缓存命中 {amount}',
+  'label.cost.input': '未命中输入 {amount}',
+  'label.cost.output': '输出 {amount}',
+  'stat.none': '暂无消耗记录',
+  'state.unavailable': '额度不可用',
+  'action.refresh': '刷新',
+  'info.aria': '花费说明',
+  'info.hint': '仅能预估 DeepSeek 相关模型。本会话花费按每条消息的发生时刻（北京时间）所在峰谷时段单价计费：缓存命中输入、未命中输入（含缓存写入）、输出（含推理）分别计价。费用按 8 月 17 日实行的标准。',
+  'badge.aria': 'DeepSeek 额度：{amount}',
+  'panel.aria': 'DeepSeek 额度详情',
+} as const
+
+/** English dictionary, key-identical to the Chinese source of truth. */
+export const en: Record<BillingKey, string> = {
+  'trigger.balance': 'Balance: {amount}',
+  'trigger.conversationSpend': 'This conversation: {amount}',
+  'label.amount': 'API balance: {amount}',
+  'label.sessionSpend': 'This session: {amount}',
+  'label.todaySpend': 'Today total: {amount}',
+  'label.cost.hit': 'Cache hit {amount}',
+  'label.cost.input': 'Missed input {amount}',
+  'label.cost.output': 'Output {amount}',
+  'stat.none': 'No usage recorded',
+  'state.unavailable': 'Balance unavailable',
+  'action.refresh': 'Refresh',
+  'info.aria': 'About this spend',
+  'info.hint': "Only DeepSeek models are estimated. This session's spend is priced per message at the rate of its Beijing-time peak/off-peak hour: cache-hit input, cache-miss input (including cache writes), and output (including reasoning) are billed separately. Pricing follows the August 17 rates.",
+  'badge.aria': 'DeepSeek balance {amount}',
+  'panel.aria': 'DeepSeek balance details',
+}
+
+/** Key domain of the `billing` namespace (zh is the source of truth). */
+export type BillingKey = keyof typeof zh

package/packages/ui-billing/src/css-modules.d.ts

@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'

package/packages/ui-billing/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Account-balance badge plugin, node half. Pure UI plugin: the empty apply
+ * exists so the plugin appears in the host cordis.yml / Loader; the browser
+ * half ships via exports["./client"], discovered through the package.json
+ * dshClient declaration.
+ */
+
+/** Host plugin body — no host-side behavior for this source plugin. */
+export function apply(): void {}

package/packages/ui-billing/src/invariant.ts

@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@rayadesu/dsh-client-ui-billing`.
+ * @module @rayadesu/dsh-client-ui-billing/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from '@deepseek-ai/cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@rayadesu/dsh-client-ui-billing'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-billing-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package is a read-only projection of one Remote
+ * snapshot onto one header slot entry. It emits no cordis events, owns no
+ * cross-plugin mutable state, and its single slot registration proves disposal
+ * through the HMR-safety spec.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */