@rayadesu/dsh-llm-billing 0.1.0 → 0.2.0

package/lib/typert.host.js

@@ -1,7 +1,7 @@
 /* Generated by @deepseek-ai/dsh-typert-generator from FaceModel — do not edit. */
 import { z } from 'zod'
 
-const _deepseek_ai_dsh_llm_billing_billing_getBalance_result$schema = z.object({
+const _rayadesu_dsh_llm_billing_billing_getBalance_result$schema = z.object({
   'isAvailable': z.boolean(),
   'lines': z.array(z.object({
   'currency': z.string(),
@@ -10,8 +10,8 @@ const _deepseek_ai_dsh_llm_billing_billing_getBalance_result$schema = z.object({
   'toppedUp': z.string(),
 })),
 })
-const _deepseek_ai_dsh_llm_billing_billing_getSessionSpend_parameter_0$schema = z.intersection(z.string(), z.unknown())
-const _deepseek_ai_dsh_llm_billing_billing_getSessionSpend_result$schema = z.object({
+const _rayadesu_dsh_llm_billing_billing_getSessionSpend_parameter_0$schema = z.intersection(z.string(), z.unknown())
+const _rayadesu_dsh_llm_billing_billing_getSessionSpend_result$schema = z.object({
   'total': z.number(),
   'models': z.array(z.object({
   'model': z.string(),
@@ -27,7 +27,8 @@ const _deepseek_ai_dsh_llm_billing_billing_getSessionSpend_result$schema = z.obj
   'outputCost': z.number(),
 })),
 })
-const _deepseek_ai_dsh_llm_billing_billing_getTodaySpend_result$schema = z.object({
+const _rayadesu_dsh_llm_billing_billing_getTodaySpend_parameter_0$schema = z.union([z.undefined(), z.literal(false), z.literal(true)])
+const _rayadesu_dsh_llm_billing_billing_getTodaySpend_result$schema = z.object({
   'total': z.number(),
   'models': z.array(z.object({
   'model': z.string(),
@@ -61,9 +62,9 @@ export const TYPERT = {
       result: {
         mode: 'strict',
         typeSymbol: '@rayadesu/dsh-llm-billing/types#DeepSeekBalance',
-        schema: _deepseek_ai_dsh_llm_billing_billing_getBalance_result$schema,
+        schema: _rayadesu_dsh_llm_billing_billing_getBalance_result$schema,
       },
-      sourceLocation: {"file":"packages/llm/llm-billing/src/balance.ts","line":139,"column":3},
+      sourceLocation: {"file":"packages/llm/llm-billing/src/balance.ts","line":143,"column":3},
     },
     {
       id: '@rayadesu/dsh-llm-billing#billing/getSessionSpend',
@@ -79,16 +80,16 @@ export const TYPERT = {
           codec: {
             mode: 'strict',
             typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
-            schema: _deepseek_ai_dsh_llm_billing_billing_getSessionSpend_parameter_0$schema,
+            schema: _rayadesu_dsh_llm_billing_billing_getSessionSpend_parameter_0$schema,
           },
         },
       ],
       result: {
         mode: 'strict',
         typeSymbol: '@rayadesu/dsh-llm-billing/types#DeepSeekSessionSpend',
-        schema: _deepseek_ai_dsh_llm_billing_billing_getSessionSpend_result$schema,
+        schema: _rayadesu_dsh_llm_billing_billing_getSessionSpend_result$schema,
       },
-      sourceLocation: {"file":"packages/llm/llm-billing/src/balance.ts","line":149,"column":3},
+      sourceLocation: {"file":"packages/llm/llm-billing/src/balance.ts","line":154,"column":3},
     },
     {
       id: '@rayadesu/dsh-llm-billing#billing/getTodaySpend',
@@ -97,13 +98,24 @@ export const TYPERT = {
       method: 'getTodaySpend',
       invocation: { kind: 'direct' },
       parameters: [
+        {
+          name: 'force',
+          wire: 'force',
+          source: 'json',
+          acceptsUndefined: true,
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@rayadesu/dsh-llm-billing#billing/getTodaySpend:force',
+            schema: _rayadesu_dsh_llm_billing_billing_getTodaySpend_parameter_0$schema,
+          },
+        },
       ],
       result: {
         mode: 'strict',
         typeSymbol: '@rayadesu/dsh-llm-billing/types#DeepSeekTodaySpend',
-        schema: _deepseek_ai_dsh_llm_billing_billing_getTodaySpend_result$schema,
+        schema: _rayadesu_dsh_llm_billing_billing_getTodaySpend_result$schema,
       },
-      sourceLocation: {"file":"packages/llm/llm-billing/src/balance.ts","line":159,"column":3},
+      sourceLocation: {"file":"packages/llm/llm-billing/src/balance.ts","line":167,"column":3},
     },
   ],
   model: {

package/lib/typert.remote-client.d.ts

@@ -3,19 +3,19 @@ import type {
   RemoteResult,
   TypertRemoteContribution,
 } from '@deepseek-ai/dsh-typert-protocol'
-import type { DeepSeekBalance, DeepSeekSessionSpend, DeepSeekTodaySpend } from '@rayadesu/dsh-llm-billing/types'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { DeepSeekBalance, DeepSeekSessionSpend, DeepSeekTodaySpend } from '@rayadesu/dsh-llm-billing/types'
 
 declare module '@deepseek-ai/dsh-typert-protocol' {
   interface TypertRemoteNamespace$62696c6c696e67 {
     getBalance: () => Promise<RemoteResult<DeepSeekBalance>>
     getSessionSpend: (sessionId: SessionId) => Promise<RemoteResult<DeepSeekSessionSpend>>
-    getTodaySpend: () => Promise<RemoteResult<DeepSeekTodaySpend>>
+    getTodaySpend: (force?: boolean) => Promise<RemoteResult<DeepSeekTodaySpend>>
   }
   interface TypertRemoteMap {
     'billing/getBalance': () => Promise<RemoteResult<DeepSeekBalance>>
     'billing/getSessionSpend': (sessionId: SessionId) => Promise<RemoteResult<DeepSeekSessionSpend>>
-    'billing/getTodaySpend': () => Promise<RemoteResult<DeepSeekTodaySpend>>
+    'billing/getTodaySpend': (force?: boolean) => Promise<RemoteResult<DeepSeekTodaySpend>>
   }
   interface TypertRemoteNamespaceMap {
     'billing': TypertRemoteNamespace$62696c6c696e67

package/lib/typert.remote-client.js

@@ -1,7 +1,7 @@
 /* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */
 import { z } from 'zod'
 
-const _deepseek_ai_dsh_llm_billing_billing_getBalance_result$schema = z.object({
+const _rayadesu_dsh_llm_billing_billing_getBalance_result$schema = z.object({
   'isAvailable': z.boolean(),
   'lines': z.array(z.object({
   'currency': z.string(),
@@ -10,8 +10,8 @@ const _deepseek_ai_dsh_llm_billing_billing_getBalance_result$schema = z.object({
   'toppedUp': z.string(),
 })),
 })
-const _deepseek_ai_dsh_llm_billing_billing_getSessionSpend_parameter_0$schema = z.intersection(z.string(), z.unknown())
-const _deepseek_ai_dsh_llm_billing_billing_getSessionSpend_result$schema = z.object({
+const _rayadesu_dsh_llm_billing_billing_getSessionSpend_parameter_0$schema = z.intersection(z.string(), z.unknown())
+const _rayadesu_dsh_llm_billing_billing_getSessionSpend_result$schema = z.object({
   'total': z.number(),
   'models': z.array(z.object({
   'model': z.string(),
@@ -27,7 +27,8 @@ const _deepseek_ai_dsh_llm_billing_billing_getSessionSpend_result$schema = z.obj
   'outputCost': z.number(),
 })),
 })
-const _deepseek_ai_dsh_llm_billing_billing_getTodaySpend_result$schema = z.object({
+const _rayadesu_dsh_llm_billing_billing_getTodaySpend_parameter_0$schema = z.union([z.undefined(), z.literal(false), z.literal(true)])
+const _rayadesu_dsh_llm_billing_billing_getTodaySpend_result$schema = z.object({
   'total': z.number(),
   'models': z.array(z.object({
   'model': z.string(),
@@ -58,9 +59,9 @@ export const TYPERT_REMOTE = {
       result: {
         mode: 'strict',
         typeSymbol: '@rayadesu/dsh-llm-billing/types#DeepSeekBalance',
-        schema: _deepseek_ai_dsh_llm_billing_billing_getBalance_result$schema,
+        schema: _rayadesu_dsh_llm_billing_billing_getBalance_result$schema,
       },
-      sourceLocation: {"file":"packages/llm/llm-billing/src/balance.ts","line":139,"column":3},
+      sourceLocation: {"file":"packages/llm/llm-billing/src/balance.ts","line":143,"column":3},
     },
     {
       id: '@rayadesu/dsh-llm-billing#billing/getSessionSpend',
@@ -76,16 +77,16 @@ export const TYPERT_REMOTE = {
           codec: {
             mode: 'strict',
             typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
-            schema: _deepseek_ai_dsh_llm_billing_billing_getSessionSpend_parameter_0$schema,
+            schema: _rayadesu_dsh_llm_billing_billing_getSessionSpend_parameter_0$schema,
           },
         },
       ],
       result: {
         mode: 'strict',
         typeSymbol: '@rayadesu/dsh-llm-billing/types#DeepSeekSessionSpend',
-        schema: _deepseek_ai_dsh_llm_billing_billing_getSessionSpend_result$schema,
+        schema: _rayadesu_dsh_llm_billing_billing_getSessionSpend_result$schema,
       },
-      sourceLocation: {"file":"packages/llm/llm-billing/src/balance.ts","line":149,"column":3},
+      sourceLocation: {"file":"packages/llm/llm-billing/src/balance.ts","line":154,"column":3},
     },
     {
       id: '@rayadesu/dsh-llm-billing#billing/getTodaySpend',
@@ -94,13 +95,24 @@ export const TYPERT_REMOTE = {
       method: 'getTodaySpend',
       invocation: { kind: 'direct' },
       parameters: [
+        {
+          name: 'force',
+          wire: 'force',
+          source: 'json',
+          acceptsUndefined: true,
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@rayadesu/dsh-llm-billing#billing/getTodaySpend:force',
+            schema: _rayadesu_dsh_llm_billing_billing_getTodaySpend_parameter_0$schema,
+          },
+        },
       ],
       result: {
         mode: 'strict',
         typeSymbol: '@rayadesu/dsh-llm-billing/types#DeepSeekTodaySpend',
-        schema: _deepseek_ai_dsh_llm_billing_billing_getTodaySpend_result$schema,
+        schema: _rayadesu_dsh_llm_billing_billing_getTodaySpend_result$schema,
       },
-      sourceLocation: {"file":"packages/llm/llm-billing/src/balance.ts","line":159,"column":3},
+      sourceLocation: {"file":"packages/llm/llm-billing/src/balance.ts","line":167,"column":3},
     },
   ],
 }

package/lib/types/balance.d.ts

@@ -32,8 +32,12 @@ export interface DeepSeekBalanceGatewayOptions {
     fetchBalance: () => Promise<DeepSeekBalance>;
     /** Compute one session's billed spend through the plugin's resolved facts. */
     fetchSessionSpend: (sessionId: SessionId) => Promise<DeepSeekSessionSpend>;
-    /** Compute today's billed spend across every session through the plugin's resolved facts. */
-    fetchTodaySpend: () => Promise<DeepSeekTodaySpend>;
+    /**
+     * Compute today's billed spend across every session through the plugin's
+     * resolved facts. `force` bypasses the host-side time window (the manual
+     * refresh path); a `force` miss still reuses revision-gated increments.
+     */
+    fetchTodaySpend: (force?: boolean) => Promise<DeepSeekTodaySpend>;
 }
 /**
  * Remote-only service exposing the DeepSeek account balance and session spend.
@@ -64,9 +68,12 @@ export declare class DeepSeekBalanceGateway extends TypertRemoteService {
     /**
      * Read today's billed spend across every session, priced per event by its
      * Beijing-time calendar day, hour, and weekday (weekends are always off-peak).
+     * @param force - bypass the host-side 60s cache (manual refresh); omitted
+     *   means a cached read. Remote parameters cannot carry default values, so
+     *   the thunk receives `undefined` for an omitted argument.
      * @returns today's total cost plus one row per priced model.
      */
-    getTodaySpend(): Promise<DeepSeekTodaySpend>;
+    getTodaySpend(force?: boolean): Promise<DeepSeekTodaySpend>;
 }
 export default DeepSeekBalanceGateway;
 //# sourceMappingURL=balance.d.ts.map

package/lib/types/balance.js

@@ -176,10 +176,13 @@ let DeepSeekBalanceGateway = (() => {
         /**
          * Read today's billed spend across every session, priced per event by its
          * Beijing-time calendar day, hour, and weekday (weekends are always off-peak).
+         * @param force - bypass the host-side 60s cache (manual refresh); omitted
+         *   means a cached read. Remote parameters cannot carry default values, so
+         *   the thunk receives `undefined` for an omitted argument.
          * @returns today's total cost plus one row per priced model.
          */
-        getTodaySpend() {
-            return this.options.fetchTodaySpend();
+        getTodaySpend(force) {
+            return this.options.fetchTodaySpend(force ?? false);
         }
     };
 })();

package/lib/types/billing.d.ts

@@ -3,6 +3,12 @@
  * pricing. Pure functions over session events and the pricing table, so the
  * Remote gateway stays transport-free and the whole spend is testable without
  * a key.
+ *
+ * The per-event pricing lives in {@link priceEvent}, the one shared fold
+ * primitive: the events-scan paths ({@link computeSessionSpend},
+ * {@link computeTodaySpend}) and the session-projection unit
+ * (`billingTodaySpend` in projection.ts) all fold the same contribution, so a
+ * pricing-table change cannot drift one path from the others.
  * @module @rayadesu/dsh-llm-billing/billing
  */
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
@@ -78,6 +84,8 @@ export interface ResolvedBilling {
  * @returns the resolved table and peak-hour windows.
  */
 export declare function resolveBilling(config: BillingConfig | undefined): ResolvedBilling;
+/** The Beijing (Asia/Shanghai, UTC+8, no DST) calendar-day key of a timestamp. */
+export declare function beijingDayKey(now: Date): string;
 /**
  * Whether a timestamp falls inside any peak-hour window (Beijing time,
  * weekdays Monday–Friday only). Weekends (Saturday and Sunday) are always
@@ -87,6 +95,70 @@ export declare function resolveBilling(config: BillingConfig | undefined): Resol
  * @returns true during a weekday peak hour.
  */
 export declare function isPeak(billing: ResolvedBilling, now: Date): boolean;
+/**
+ * One priced billed event's contribution: the model row plus the Beijing
+ * calendar day its timestamp falls on. `undefined` when the event carries no
+ * priced usage (not an `assistant/message`, no usage report, or a model
+ * without a pricing row).
+ */
+export interface BillingEventContribution {
+    /** Beijing-time calendar-day key of the event's timestamp. */
+    dayKey: string;
+    /** Wire model id, e.g. `deepseek-v4-flash`. */
+    model: string;
+    /** Selector label for the model. */
+    displayName: string;
+    /** Billed cost in CNY (peak plus off-peak portions). */
+    cost: number;
+    /** Cost portion billed at peak rates. */
+    peakCost: number;
+    /** Cost portion billed at off-peak rates. */
+    offPeakCost: number;
+    /** Cache-hit input tokens billed at the hit rate. */
+    cacheHitInputTokens: number;
+    /** Cache-miss input tokens (uncached input plus cache writes), billed at the miss rate. */
+    cacheMissInputTokens: number;
+    /** Output tokens (reasoning included), billed at the output rate. */
+    outputTokens: number;
+    /** Billed cost of cache-hit input tokens in CNY. */
+    cacheHitInputCost: number;
+    /** Billed cost of cache-miss input tokens (uncached input plus cache writes) in CNY. */
+    cacheMissInputCost: number;
+    /** Billed cost of output tokens (reasoning included) in CNY. */
+    outputCost: number;
+}
+/**
+ * Price one event at the official per-model rates, applying the peak/off-peak
+ * table by its Beijing-time hour and weekday (peak windows apply Monday–Friday
+ * only; weekends are off-peak). Each `assistant/message` event with usage
+ * contributes cache-hit input, cache-miss input (uncached input plus cache
+ * writes), and output (reasoning included) tokens at the rate of its own
+ * timestamp; a model with usage but no pricing row contributes nothing (the
+ * published table prices only the two V4 rows).
+ * @param event - the event to price.
+ * @param billing - resolved pricing with peak-hour windows.
+ * @param names - model id → display label.
+ * @returns the priced contribution, or `undefined` when the event has no priced usage.
+ */
+export declare function priceEvent(event: SessionEvent, billing: ResolvedBilling, names: ReadonlyMap<string, string>): BillingEventContribution | undefined;
+/** A spend with no priced usage. */
+export declare function emptyTodaySpend(): DeepSeekTodaySpend;
+/**
+ * Merge one priced event's contribution into an accumulator spend (pure:
+ * returns a new spend, never mutates its input).
+ * @param spend - the accumulator (per session and day, or across sessions).
+ * @param priced - the priced contribution to add.
+ * @returns the merged spend.
+ */
+export declare function addEventContribution(spend: DeepSeekTodaySpend, priced: BillingEventContribution): DeepSeekTodaySpend;
+/**
+ * Sum two spends (per session and day, or across sessions) into one (pure:
+ * returns a new spend, never mutates its inputs).
+ * @param target - the accumulator spend.
+ * @param source - the spend to add.
+ * @returns the summed spend.
+ */
+export declare function mergeTodaySpend(target: DeepSeekTodaySpend, source: DeepSeekTodaySpend): DeepSeekTodaySpend;
 /**
  * Price one session's complete event log at the official per-model rates.
  * @param events - one session's complete event log.

package/lib/types/billing.js

@@ -3,6 +3,12 @@
  * pricing. Pure functions over session events and the pricing table, so the
  * Remote gateway stays transport-free and the whole spend is testable without
  * a key.
+ *
+ * The per-event pricing lives in {@link priceEvent}, the one shared fold
+ * primitive: the events-scan paths ({@link computeSessionSpend},
+ * {@link computeTodaySpend}) and the session-projection unit
+ * (`billingTodaySpend` in projection.ts) all fold the same contribution, so a
+ * pricing-table change cannot drift one path from the others.
  * @module @rayadesu/dsh-llm-billing/billing
  */
 /**
@@ -67,7 +73,7 @@ function beijingWeekday(now) {
     return new Date(now.getTime() + 8 * 3_600_000).getUTCDay();
 }
 /** The Beijing (Asia/Shanghai, UTC+8, no DST) calendar-day key of a timestamp. */
-function beijingDayKey(now) {
+export function beijingDayKey(now) {
     return new Date(now.getTime() + 8 * 3_600_000).toISOString().slice(0, 10);
 }
 /**
@@ -85,6 +91,127 @@ export function isPeak(billing, now) {
     const hour = beijingHour(now);
     return billing.peakHours.some(({ start, end }) => hour >= start && hour < end);
 }
+/**
+ * Price one event at the official per-model rates, applying the peak/off-peak
+ * table by its Beijing-time hour and weekday (peak windows apply Monday–Friday
+ * only; weekends are off-peak). Each `assistant/message` event with usage
+ * contributes cache-hit input, cache-miss input (uncached input plus cache
+ * writes), and output (reasoning included) tokens at the rate of its own
+ * timestamp; a model with usage but no pricing row contributes nothing (the
+ * published table prices only the two V4 rows).
+ * @param event - the event to price.
+ * @param billing - resolved pricing with peak-hour windows.
+ * @param names - model id → display label.
+ * @returns the priced contribution, or `undefined` when the event has no priced usage.
+ */
+export function priceEvent(event, billing, names) {
+    if (event.type !== 'assistant/message')
+        return undefined;
+    const reported = event.data.usage;
+    if (reported === undefined)
+        return undefined;
+    const model = event.data.message.source.model;
+    const pricing = billing.models.get(model);
+    if (pricing === undefined)
+        return undefined;
+    const time = new Date(event.time);
+    const peak = isPeak(billing, time);
+    const price = peak ? pricing.peak : pricing.offPeak;
+    const hit = reported.cacheReadTokens ?? 0;
+    const miss = reported.inputTokens + (reported.cacheWriteTokens ?? 0);
+    const output = reported.outputTokens;
+    const hitCost = (hit * price.cacheHitInput) / 1_000_000;
+    const missCost = (miss * price.cacheMissInput) / 1_000_000;
+    const outputCost = (output * price.output) / 1_000_000;
+    const cost = hitCost + missCost + outputCost;
+    return {
+        dayKey: beijingDayKey(time),
+        model,
+        displayName: names.get(model) ?? model,
+        cost,
+        peakCost: peak ? cost : 0,
+        offPeakCost: peak ? 0 : cost,
+        cacheHitInputTokens: hit,
+        cacheMissInputTokens: miss,
+        outputTokens: output,
+        cacheHitInputCost: hitCost,
+        cacheMissInputCost: missCost,
+        outputCost,
+    };
+}
+/** A spend with no priced usage. */
+export function emptyTodaySpend() {
+    return { total: 0, models: [] };
+}
+/** The today-spend shape of a single priced contribution. */
+function contributionModel(priced) {
+    return {
+        model: priced.model,
+        displayName: priced.displayName,
+        cost: priced.cost,
+        peakCost: priced.peakCost,
+        offPeakCost: priced.offPeakCost,
+        cacheHitInputTokens: priced.cacheHitInputTokens,
+        cacheMissInputTokens: priced.cacheMissInputTokens,
+        outputTokens: priced.outputTokens,
+        cacheHitInputCost: priced.cacheHitInputCost,
+        cacheMissInputCost: priced.cacheMissInputCost,
+        outputCost: priced.outputCost,
+    };
+}
+/**
+ * Merge one priced event's contribution into an accumulator spend (pure:
+ * returns a new spend, never mutates its input).
+ * @param spend - the accumulator (per session and day, or across sessions).
+ * @param priced - the priced contribution to add.
+ * @returns the merged spend.
+ */
+export function addEventContribution(spend, priced) {
+    const rows = spend.models.map(row => row.model === priced.model
+        ? {
+            ...row,
+            cost: row.cost + priced.cost,
+            peakCost: row.peakCost + priced.peakCost,
+            offPeakCost: row.offPeakCost + priced.offPeakCost,
+            cacheHitInputTokens: row.cacheHitInputTokens + priced.cacheHitInputTokens,
+            cacheMissInputTokens: row.cacheMissInputTokens + priced.cacheMissInputTokens,
+            outputTokens: row.outputTokens + priced.outputTokens,
+            cacheHitInputCost: row.cacheHitInputCost + priced.cacheHitInputCost,
+            cacheMissInputCost: row.cacheMissInputCost + priced.cacheMissInputCost,
+            outputCost: row.outputCost + priced.outputCost,
+        }
+        : row);
+    if (!rows.some(row => row.model === priced.model))
+        rows.push(contributionModel(priced));
+    return { total: spend.total + priced.cost, models: rows };
+}
+/**
+ * Sum two spends (per session and day, or across sessions) into one (pure:
+ * returns a new spend, never mutates its inputs).
+ * @param target - the accumulator spend.
+ * @param source - the spend to add.
+ * @returns the summed spend.
+ */
+export function mergeTodaySpend(target, source) {
+    let merged = target;
+    for (const row of source.models) {
+        merged = addEventContribution(merged, {
+            dayKey: '',
+            model: row.model,
+            displayName: row.displayName,
+            cost: row.cost,
+            peakCost: row.peakCost,
+            offPeakCost: row.offPeakCost,
+            cacheHitInputTokens: row.cacheHitInputTokens,
+            cacheMissInputTokens: row.cacheMissInputTokens,
+            outputTokens: row.outputTokens,
+            cacheHitInputCost: row.cacheHitInputCost,
+            cacheMissInputCost: row.cacheMissInputCost,
+            outputCost: row.outputCost,
+        });
+    }
+    return merged;
+}
 /**
  * Price a set of billed events at the official per-model rates, applying the
  * peak/off-peak table per event by its Beijing-time hour and weekday (peak
@@ -101,64 +228,14 @@ export function isPeak(billing, now) {
  */
 function priceEvents(events, billing, catalog) {
     const names = new Map(catalog.map(model => [model.id, model.name]));
-    const rows = new Map();
+    let spend = { total: 0, models: [] };
     for (const event of events) {
-        if (event.type !== 'assistant/message')
-            continue;
-        const reported = event.data.usage;
-        if (reported === undefined)
+        const priced = priceEvent(event, billing, names);
+        if (priced === undefined)
             continue;
-        const model = event.data.message.source.model;
-        const pricing = billing.models.get(model);
-        if (pricing === undefined)
-            continue;
-        const peak = isPeak(billing, new Date(event.time));
-        const price = peak ? pricing.peak : pricing.offPeak;
-        const hit = reported.cacheReadTokens ?? 0;
-        const miss = reported.inputTokens + (reported.cacheWriteTokens ?? 0);
-        const output = reported.outputTokens;
-        const hitCost = (hit * price.cacheHitInput) / 1_000_000;
-        const missCost = (miss * price.cacheMissInput) / 1_000_000;
-        const outputCost = (output * price.output) / 1_000_000;
-        const cost = hitCost + missCost + outputCost;
-        let row = rows.get(model);
-        if (row === undefined) {
-            row = {
-                cacheHitInputTokens: 0, cacheMissInputTokens: 0, outputTokens: 0,
-                cost: 0, peakCost: 0, offPeakCost: 0,
-                cacheHitInputCost: 0, cacheMissInputCost: 0, outputCost: 0,
-            };
-            rows.set(model, row);
-        }
-        row.cacheHitInputTokens += hit;
-        row.cacheMissInputTokens += miss;
-        row.outputTokens += output;
-        row.cost += cost;
-        row.cacheHitInputCost += hitCost;
-        row.cacheMissInputCost += missCost;
-        row.outputCost += outputCost;
-        if (peak)
-            row.peakCost += cost;
-        else
-            row.offPeakCost += cost;
+        spend = addEventContribution(spend, priced);
     }
-    const models = [...rows.entries()].map(([model, row]) => ({
-        model,
-        displayName: names.get(model) ?? model,
-        cost: row.cost,
-        peakCost: row.peakCost,
-        offPeakCost: row.offPeakCost,
-        cacheHitInputTokens: row.cacheHitInputTokens,
-        cacheMissInputTokens: row.cacheMissInputTokens,
-        outputTokens: row.outputTokens,
-        cacheHitInputCost: row.cacheHitInputCost,
-        cacheMissInputCost: row.cacheMissInputCost,
-        outputCost: row.outputCost,
-    }));
-    return {
-        total: models.reduce((sum, model) => sum + model.cost, 0),
-        models,
-    };
+    return spend;
 }
 /**
  * Price one session's complete event log at the official per-model rates.
@@ -182,6 +259,14 @@ export function computeSessionSpend(events, billing, catalog) {
  */
 export function computeTodaySpend(events, billing, catalog, now = new Date()) {
     const day = beijingDayKey(now);
-    return priceEvents(events.filter(event => beijingDayKey(new Date(event.time)) === day), billing, catalog);
+    const names = new Map(catalog.map(model => [model.id, model.name]));
+    let spend = emptyTodaySpend();
+    for (const event of events) {
+        const priced = priceEvent(event, billing, names);
+        if (priced === undefined || priced.dayKey !== day)
+            continue;
+        spend = addEventContribution(spend, priced);
+    }
+    return spend;
 }
 //# sourceMappingURL=billing.js.map

package/lib/types/index.d.ts

@@ -4,15 +4,28 @@
  * the credential/environment seams, prices each session's billed usage with the
  * peak/off-peak table, and exposes the `billing` Remote (`getBalance`, the
  * per-session `getSessionSpend`, and the all-sessions `getTodaySpend`).
+ *
+ * Today's spend never scans every session log per request: a 60-second
+ * Beijing-day cache with in-flight coalescing serves the message-triggered
+ * reads, the manual refresh may bypass the time window (`force`), and the
+ * computation behind a miss reads only sessions whose persisted revision
+ * changed since the last resolution (see today-spend.ts). When the
+ * session-projection registry is composed, the plugin additionally registers
+ * the `billingTodaySpend` projection unit, which folds each session's spend
+ * eagerly and lets cold reads ride the projection-cache ladder.
  * @module @rayadesu/dsh-llm-billing
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { BillingConfig } from './billing.ts';
 export { DeepSeekBalanceGateway, fetchDeepSeekBalance, parseDeepSeekBalance } from './balance.ts';
-export { computeSessionSpend, computeTodaySpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, isPeak, resolveBilling, } from './billing.ts';
-export type { BillingConfig, BillingConfigModel, DeepSeekModelPricing, DeepSeekTokenPrice, PeakHourWindow, ResolvedBilling, } from './billing.ts';
+export { addEventContribution, beijingDayKey, computeSessionSpend, computeTodaySpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, emptyTodaySpend, isPeak, mergeTodaySpend, priceEvent, resolveBilling, } from './billing.ts';
+export type { BillingConfig, BillingConfigModel, BillingEventContribution, DeepSeekModelPricing, DeepSeekTokenPrice, PeakHourWindow, ResolvedBilling, } from './billing.ts';
 export type * from './types.ts';
+export { BILLING_UNIT_KEY, billingTodaySpendDefinition, foldBillingUnit } from './projection.ts';
+export type { BillingUnitState } from './projection.ts';
+export { TodaySpendCache, TodaySpendScanner } from './today-spend.ts';
+export type { ScannerPersistedHeader, ScannerSession, TodaySpendScannerDeps } from './today-spend.ts';
 export declare const name = "llm-billing";
 /** Public API default; deployments may point elsewhere via $DEEPSEEK_BASE_URL. */
 export declare const PUBLIC_BASE_URL = "https://api.deepseek.com";
@@ -40,6 +53,10 @@ export interface Config {
     billing?: BillingConfig;
 }
 export declare const Config: z<Config>;
+/** How often a Beijing-day "today spend" value may be recomputed (60s). */
+export declare const TODAY_SPEND_CACHE_MS = 60000;
+/** Hard cap on today's events collected by the events scan path. */
+export declare const TODAY_SPEND_MAX_EVENTS = 200000;
 /**
  * Register the `billing` Remote under the `billing` namespace.
  * @param ctx - owning plugin context.