@linxin666/dsh-usage 0.3.20 → 0.3.21

package/src/client/voucher.ts

@@ -0,0 +1,144 @@
+/**
+ * The Whale-yuan voucher (鲸元券): the DeepSeek official family's retained
+ * ledger totals stamped onto the banknote artwork as a denomination, ready
+ * to save or share. The canvas copy is deliberately locale-neutral (digits,
+ * latin captions, ISO dates) so the exported image needs no dictionary;
+ * everything user-facing around it lives in the section's locales. The pure
+ * helpers are unit-tested; the draw itself degrades to a thrown error the
+ * section renders as its failure line.
+ * @module @linxin666/dsh-usage/client/voucher
+ */
+
+import { isDeepSeekProviderRoute } from '../core/adapters.ts'
+import { totalTokens } from '../core/ledger.ts'
+import type { UsageWindowSummary } from '../core/types.ts'
+import { VOUCHER_ART_DATA_URL } from './voucher-art.generated.ts'
+
+/** The facts stamped onto one voucher. */
+export interface VoucherData {
+  /** DeepSeek official family total tokens over the retained window. */
+  tokens: number
+  /** Provider calls that reported usage. */
+  calls: number
+  /** Fold-time spend estimate in CNY (the only priced family). */
+  cost: number
+  /** Retained window bounds (local date keys, inclusive). */
+  from: string
+  to: string
+}
+
+/** Anti-inflation exchange rate: 1000 tokens mint one whale yuan. */
+export const TOKENS_PER_WHALE_YUAN = 1000
+
+/** The note's face value in whale yuan; the smallest denomination is 1. */
+export function faceValue(tokens: number): number {
+  return Math.max(1, Math.round(tokens / TOKENS_PER_WHALE_YUAN))
+}
+
+/** Local calendar day (`YYYY-MM-DD`) for an epoch ms timestamp. */
+export function formatDay(ms: number): string {
+  const date = new Date(ms)
+  const month = String(date.getMonth() + 1).padStart(2, '0')
+  const day = String(date.getDate()).padStart(2, '0')
+  return `${date.getFullYear()}-${month}-${day}`
+}
+
+/**
+ * Sum the DeepSeek official family rows out of a usage window (both the
+ * `deepseek` catalog alias and the live `deepseek-official` route fold into
+ * one voucher). Undefined when the window is absent (older host) or the
+ * family has no usage — a zero-token note mints nothing.
+ */
+export function deepseekVoucherData(window: UsageWindowSummary | undefined): VoucherData | undefined {
+  if (window === undefined) return undefined
+  let tokens = 0
+  let calls = 0
+  let cost = 0
+  for (const row of window.providers) {
+    if (!isDeepSeekProviderRoute(row.provider)) continue
+    tokens += totalTokens(row.totals)
+    calls += row.totals.calls
+    cost += row.totals.cost
+  }
+  if (tokens <= 0) return undefined
+  return { tokens, calls, cost, from: window.from, to: window.to }
+}
+
+/** Banknote denomination: full digits with thousands separators. */
+export function formatDenomination(value: number): string {
+  return Math.max(0, Math.round(value)).toLocaleString('en-US')
+}
+
+/** Deterministic serial number flavor: the face value mod 1e9, zero-padded. */
+export function voucherSerial(face: number): string {
+  return String(Math.max(0, Math.round(face)) % 1_000_000_000).padStart(9, '0')
+}
+
+/** The decoded note artwork plus its intrinsic size. */
+export interface VoucherArt {
+  image: CanvasImageSource
+  width: number
+  height: number
+}
+
+let artPromise: Promise<VoucherArt> | undefined
+
+/** Decode the note artwork once per page; a failed decode retries next call. */
+export function loadVoucherArt(): Promise<VoucherArt> {
+  artPromise ??= new Promise<VoucherArt>((resolve, reject) => {
+    const image = new Image()
+    image.onload = () => resolve({ image, width: image.naturalWidth, height: image.naturalHeight })
+    image.onerror = () => {
+      artPromise = undefined
+      reject(new Error('voucher art decode failed'))
+    }
+    image.src = VOUCHER_ART_DATA_URL
+  })
+  return artPromise
+}
+
+/** Ink and seal-red the note's engraving palette, sampled off the artwork. */
+const INK = '#2b2f38'
+const SEAL_RED = '#9a3b2c'
+const DENOMINATION_FONT = "Georgia, 'Times New Roman', serif"
+
+/**
+ * Stamp the denomination block onto a canvas sized to the artwork: the
+ * minted whale yuan as the face value under the note title, a small
+ * `whale yuan` caption, and a seal-red serial line with the minting
+ * window. All geometry is relative to the artwork size so a regenerated
+ * asset reflows.
+ */
+export function drawVoucher(canvas: HTMLCanvasElement, art: VoucherArt, data: VoucherData): void {
+  canvas.width = art.width
+  canvas.height = art.height
+  const ctx = canvas.getContext('2d')
+  if (ctx === null) throw new Error('canvas 2d context unavailable')
+  ctx.drawImage(art.image, 0, 0, art.width, art.height)
+
+  const face = faceValue(data.tokens)
+  const centerX = Math.round(art.width * 0.67)
+  const denomination = formatDenomination(face)
+
+  // Fit the face value into the free band between the note title and the
+  // bottom ornament (the red seal sits to its right).
+  let size = Math.round(art.height * 0.115)
+  const minSize = Math.round(art.height * 0.055)
+  const maxWidth = art.width * 0.28
+  ctx.textAlign = 'center'
+  ctx.textBaseline = 'alphabetic'
+  while (size > minSize) {
+    ctx.font = `700 ${size}px ${DENOMINATION_FONT}`
+    if (ctx.measureText(denomination).width <= maxWidth) break
+    size -= 2
+  }
+  ctx.fillStyle = INK
+  ctx.fillText(denomination, centerX, Math.round(art.height * 0.75))
+
+  ctx.font = `600 ${Math.round(art.height * 0.032)}px ${DENOMINATION_FONT}`
+  ctx.fillText('whale yuan', centerX, Math.round(art.height * 0.8))
+
+  ctx.fillStyle = SEAL_RED
+  ctx.font = `500 ${Math.round(art.height * 0.026)}px ${DENOMINATION_FONT}`
+  ctx.fillText(`NO.${voucherSerial(face)} ${data.from} - ${data.to}`, centerX, Math.round(art.height * 0.845))
+}

package/src/core/pricing.ts

@@ -1,13 +1,19 @@
 /**
- * DeepSeek official peak/off-peak pricing: the published V4 price book plus
- * the peak-window clock, folded into a per-call spend estimate the ledger
- * stamps at fold time (the provider bills each request in the period the
- * request ran in, so pricing at the fold is the honest estimate).
+ * DeepSeek official peak/off-peak pricing: the published price book plus the
+ * peak-window clock, folded into a per-call spend estimate the ledger stamps
+ * at fold time (the provider bills each request in the period the request ran
+ * in, so pricing at the fold is the honest estimate).
  *
- * Policy (api-docs.deepseek.com pricing page, effective 2026-08-17): peak
- * hours are Beijing time Monday-Friday 09:00-12:00 and 14:00-18:00; every
- * other hour (nights, weekends) is off-peak and billed at half the peak
- * price. All prices here are CNY per million tokens.
+ * Policy (api-docs.deepseek.com pricing page, effective 2026-09-10 12:00
+ * Beijing): peak hours are Beijing time Monday-Friday 09:00-12:00 and
+ * 14:00-18:00; every other hour (nights, weekends) is off-peak and billed at
+ * half the peak price. All prices here are CNY per million tokens.
+ *
+ * The published rows are `deepseek-flash` (DeepSeek-V4.1-Flash) and
+ * `deepseek-v4-pro` (DeepSeek-V4-Pro-0813). The retired flash ids
+ * (`deepseek-v4-flash`, `deepseek-v4-flash-vision-exp`) stay accepted and bill
+ * at the flash row; DeepSeek routes `deepseek-v4-pro` to V4.1-Flash from the
+ * retirement instant below until V4.1 Pro ships.
  * @module @linxin666/dsh-usage/core/pricing
  */
 
@@ -40,20 +46,27 @@ interface ModelPrice {
   output: { offPeak: number; peak: number }
 }
 
-/** deepseek-v4-flash (and the flash-class vision experiment). */
+/** deepseek-flash (DeepSeek-V4.1-Flash), including the retired flash-class ids it now serves. */
 const FLASH_PRICE: ModelPrice = {
-  cacheHit: { offPeak: 0.05, peak: 0.1 },
-  inputMiss: { offPeak: 1.5, peak: 3.0 },
-  output: { offPeak: 4.5, peak: 9.0 },
+  cacheHit: { offPeak: 0.02, peak: 0.04 },
+  inputMiss: { offPeak: 1.0, peak: 2.0 },
+  output: { offPeak: 4.0, peak: 8.0 },
 }
 
-/** deepseek-v4-pro. */
+/** deepseek-v4-pro (DeepSeek-V4-Pro-0813); superseded by the flash row at the retirement instant. */
 const PRO_PRICE: ModelPrice = {
   cacheHit: { offPeak: 0.15, peak: 0.3 },
   inputMiss: { offPeak: 4.5, peak: 9.0 },
   output: { offPeak: 13.5, peak: 27.0 },
 }
 
+/**
+ * The instant DeepSeek starts serving `deepseek-v4-pro` requests from
+ * V4.1-Flash and billing the flash row: 2026-09-14 12:00 Beijing (UTC+8).
+ * Drop the pro row's time fence once V4.1 Pro ships with a published row.
+ */
+const V4_PRO_FOLDED_INTO_FLASH_AT_MS = Date.UTC(2026, 8, 14, 4, 0)
+
 function withinWindow(minuteOfDay: number): PeakWindow | undefined {
   return PEAK_WINDOWS.find((window) => minuteOfDay >= window.from && minuteOfDay < window.to)
 }
@@ -87,9 +100,10 @@ export function deepseekPeriodAt(ms: number): { peak: boolean; boundaryMs: numbe
   return { peak: false, boundaryMs: ms + 86_400_000 }
 }
 
-/** The price row for a model id; unknown ids take the flash-class row (documented estimate). */
-function priceFor(model: string): ModelPrice {
-  return model.includes('v4-pro') ? PRO_PRICE : FLASH_PRICE
+/** The price row for a model id at `atMs`; unknown ids take the flash-class row (documented estimate). */
+function priceFor(model: string, atMs: number): ModelPrice {
+  const proPriced = model.includes('v4-pro') && atMs < V4_PRO_FOLDED_INTO_FLASH_AT_MS
+  return proPriced ? PRO_PRICE : FLASH_PRICE
 }
 
 /**
@@ -99,7 +113,7 @@ function priceFor(model: string): ModelPrice {
  * by route family). Rounded to micro-CNY so the ledger stays readable.
  */
 export function deepseekModelSpend(model: string, totals: Readonly<UsageTokenTotals>, atMs: number): number {
-  const price = priceFor(model)
+  const price = priceFor(model, atMs)
   const period = deepseekPeriodAt(atMs)
   const column = period.peak ? 'peak' : 'offPeak'
   const spend = (totals.cacheReadTokens * price.cacheHit[column]

package/src/core/types.ts

@@ -100,6 +100,22 @@ export interface PlanView {
 /** How the credential backing one provider route was resolved. */
 export type CredentialKind = 'api-key' | 'env' | 'oauth' | 'none'
 
+/** One aggregated usage window (the 30-day trend, or the whole retained ledger). */
+export interface UsageWindowSummary {
+  from: string
+  to: string
+  totals: UsageTokenTotals
+  providers: UsageProviderSummary[]
+}
+
+/** Real spend observed from an official balance series rather than priced locally. */
+export interface ObservedSpendView {
+  /** Accrued spend in the account currency (CNY for the DeepSeek official watch). */
+  cny: number
+  /** Epoch ms of the first balance observation the accrual starts at. */
+  since: number
+}
+
 /** One provider row of the overview snapshot. */
 export interface ProviderSnapshotView {
   /** Provider route key (`deepseek`, `kimi-coding`, custom routes, ...). */
@@ -139,12 +155,20 @@ export interface UsageOverviewView {
      * The same window aggregated per provider and model — the trend card's
      * bar-chart data. Optional so an older host document still renders.
      */
-    range?: {
-      from: string
-      to: string
-      totals: UsageTokenTotals
-      providers: UsageProviderSummary[]
-    }
+    range?: UsageWindowSummary
+    /**
+     * The whole retained ledger (up to `retainDays`, today included)
+     * aggregated per provider — the voucher's minted total. Optional for the
+     * same older-host tolerance as `range`.
+     */
+    all?: UsageWindowSummary
+    /**
+     * Real CNY spend of the official DeepSeek family, accrued from observed
+     * decreases of the official balance (top-ups never count). Present once
+     * a decrease has been observed; until then the section falls back to the
+     * fold-time estimate.
+     */
+    observedSpend?: ObservedSpendView
   }
 }
 

package/src/host/usage-service.ts

@@ -18,12 +18,28 @@ import { adapterFor, isDeepSeekProviderRoute, providerErrorMessage } from '../co
 import type { BalanceParse, PlanParse } from '../core/adapters.ts'
 import { deepseekModelSpend, deepseekPeriodAt } from '../core/pricing.ts'
 import { createLedgerDocument, deserializeLedger, foldUsage, ledgerDayKeys, localDateKey, pruneLedger, summarizeDays, totalTokens } from '../core/ledger.ts'
-import type { BalanceView, CredentialKind, PlanView, ProviderSnapshotState, ProviderSnapshotView, UsageLedgerDocument, UsageOverviewView, UsageTokenTotals } from '../core/types.ts'
+import type { BalanceView, CredentialKind, ObservedSpendView, PlanView, ProviderSnapshotState, ProviderSnapshotView, UsageLedgerDocument, UsageOverviewView, UsageTokenTotals } from '../core/types.ts'
 import { emptyTotals } from '../core/types.ts'
 
 /** Source tag the plugin stamps onto pet announcements. */
 export const USAGE_ANNOUNCE_SOURCE = 'dsh-usage'
 
+/**
+ * Persisted accrual state for the official DeepSeek family's real spend:
+ * consecutive observations of the official CNY balance, decreases counted
+ * as spent (a rise is a top-up and never accrues). `since` is the first
+ * observation; the ledger keeps no such fact, so this watch is the only
+ * source of the voucher's observed-spend figure.
+ */
+export interface SpendWatch {
+  /** Total observed decrease since `since`, in CNY. */
+  accruedCny: number
+  /** Epoch ms of the first balance observation. */
+  since: number
+  /** The balance the previous observation ended on, when one exists. */
+  lastBalanceCny?: number
+}
+
 /** Per-route credential fact the probes run against. */
 interface ResolvedCredential {
   kind: CredentialKind
@@ -225,6 +241,8 @@ export class UsageService {
 
   private ledger: UsageLedgerDocument = createLedgerDocument()
   private readonly snapshots = new Map<string, ProviderSnapshotState>()
+  /** The official DeepSeek family's real-spend watch (see SpendWatch). */
+  private spendWatch: SpendWatch | undefined
   /** Per-live-session route attribution (WeakMap: disposed sessions age out). */
   private readonly sessionRoutes = new WeakMap<Session, { provider: string; model: string }>()
   /** The most recent route seen this boot; the pet bubble follows it. */
@@ -307,8 +325,10 @@ export class UsageService {
       })
     }
     providers.sort((a, b) => Number(b.supported) - Number(a.supported) || a.displayName.localeCompare(b.displayName))
-    const days = ledgerDayKeys(this.ledger).slice(-TREND_DAYS)
+    const allKeys = ledgerDayKeys(this.ledger)
+    const days = allKeys.slice(-TREND_DAYS)
     const range = summarizeDays(days.map((key) => this.ledger.days[key] ?? {}))
+    const all = summarizeDays(allKeys.map((key) => this.ledger.days[key] ?? {}))
     return {
       updatedAt: Date.now(),
       providers,
@@ -325,6 +345,15 @@ export class UsageService {
           totals: range.totals,
           providers: range.providers,
         },
+        all: {
+          from: allKeys[0] ?? todayKey,
+          to: allKeys[allKeys.length - 1] ?? todayKey,
+          totals: all.totals,
+          providers: all.providers,
+        },
+        ...(this.spendWatch !== undefined && this.spendWatch.accruedCny > 0
+          ? { observedSpend: { cny: this.spendWatch.accruedCny, since: this.spendWatch.since } satisfies ObservedSpendView }
+          : {}),
       },
     }
   }
@@ -353,6 +382,33 @@ export class UsageService {
     return row?.totals ?? emptyTotals()
   }
 
+  /**
+   * Accrue the official DeepSeek family's real spend from observed CNY
+   * balance decreases; a balance rise is a top-up and never counts. The
+   * family's route ids can alias one account, so the watch follows the
+   * largest balance seen this cycle and accrues only decreases of that
+   * series — a failed probe keeps the stale balance and accrues nothing
+   * until the next success reports the whole drop at once.
+   */
+  private accrueDeepSeekSpend(): void {
+    let balanceCny: number | undefined
+    for (const [id, snapshot] of this.snapshots) {
+      if (!isDeepSeekProviderRoute(id)) continue
+      const balance = snapshot.balance
+      if (balance === undefined || balance.currency.toUpperCase() !== 'CNY') continue
+      const value = Number(balance.totalBalance)
+      if (!Number.isFinite(value)) continue
+      balanceCny = balanceCny === undefined ? value : Math.max(balanceCny, value)
+    }
+    if (balanceCny === undefined) return
+    const watch = this.spendWatch ?? { accruedCny: 0, since: Date.now() }
+    if (watch.lastBalanceCny !== undefined && balanceCny < watch.lastBalanceCny) {
+      watch.accruedCny += watch.lastBalanceCny - balanceCny
+    }
+    watch.lastBalanceCny = balanceCny
+    this.spendWatch = watch
+  }
+
   /**
    * The display name for a route key: the LLM runtime's first, then the
    * adapter's, then the id itself — the snapshot may not exist for
@@ -437,7 +493,7 @@ export class UsageService {
         this.lastPrune = { dayKey: localDateKey(Date.now()), retainDays: this.options.retainDays }
       }
       if (rawSnapshots !== undefined) {
-        const parsed = JSON.parse(rawSnapshots) as { providers?: Record<string, ProviderSnapshotState> }
+        const parsed = JSON.parse(rawSnapshots) as { providers?: Record<string, ProviderSnapshotState>; spendWatch?: SpendWatch }
         if (typeof parsed === 'object' && parsed !== null && typeof parsed.providers === 'object' && parsed.providers !== null) {
           for (const [provider, snapshot] of Object.entries(parsed.providers)) {
             if (typeof snapshot === 'object' && snapshot !== null && typeof snapshot.provider === 'string') {
@@ -445,6 +501,17 @@ export class UsageService {
             }
           }
         }
+        // Revive the spend watch strictly: a corrupt accrual would otherwise
+        // quietly rewrite the user's real-spend figure.
+        const watch = parsed.spendWatch
+        if (typeof watch === 'object' && watch !== null && typeof watch.accruedCny === 'number' && Number.isFinite(watch.accruedCny) && watch.accruedCny >= 0
+          && typeof watch.since === 'number' && Number.isFinite(watch.since) && watch.since > 0) {
+          this.spendWatch = {
+            accruedCny: watch.accruedCny,
+            since: watch.since,
+            ...(typeof watch.lastBalanceCny === 'number' && Number.isFinite(watch.lastBalanceCny) ? { lastBalanceCny: watch.lastBalanceCny } : {}),
+          }
+        }
       }
     } catch {
       // Corrupt or unreadable state starts fresh; the next flush rewrites it.
@@ -503,7 +570,11 @@ export class UsageService {
     if (!this.loaded) return
     try {
       await mkdir(dirname(this.snapshotsPath), { recursive: true })
-      await writeJsonAtomic(this.snapshotsPath, { version: 1, providers: Object.fromEntries(this.snapshots) })
+      await writeJsonAtomic(this.snapshotsPath, {
+        version: 1,
+        providers: Object.fromEntries(this.snapshots),
+        ...(this.spendWatch !== undefined ? { spendWatch: this.spendWatch } : {}),
+      })
     } catch {
       // Same silent degradation as the ledger.
     }
@@ -549,6 +620,7 @@ export class UsageService {
           if (!seen.has(id)) this.snapshots.delete(id)
         }
         if (this.disposed) return
+        this.accrueDeepSeekSpend()
         await this.persistSnapshots()
         this.announceCurrent()
       } finally {