@rayadesu/dsh-llm-billing 0.3.8 → 0.3.10

package/lib/types/billing.d.ts

@@ -12,8 +12,9 @@
  * from the others.
  * @module @rayadesu/dsh-llm-billing/billing
  */
+import type { TokenUsage } from '@deepseek-ai/dsh-llm';
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
-import type { DeepSeekSessionSpend, DeepSeekTodaySpend, DeepSeekTurnSpend } from './types.ts';
+import type { DeepSeekSessionSpend, DeepSeekSessionTurnSpends, DeepSeekTodaySpend, DeepSeekTurnSpend } from './types.ts';
 /** One token price point, in CNY per 1M tokens. */
 export interface DeepSeekTokenPrice {
     /** 1M input cache-hit tokens. */
@@ -23,21 +24,41 @@ export interface DeepSeekTokenPrice {
     /** 1M output tokens. */
     output: number;
 }
-/** Peak and off-peak price pair for one model. */
-export interface DeepSeekModelPricing {
+/**
+ * One published peak/off-peak rate revision of a model: the price pair plus the
+ * instant it took effect. A provider re-prices a series without repricing its
+ * history, so the table keeps every revision and prices each sample at the
+ * rates of the sample's own timestamp.
+ */
+export interface DeepSeekRateRevision {
     /** Price during peak hours. */
     peak: DeepSeekTokenPrice;
     /** Price during off-peak hours. */
     offPeak: DeepSeekTokenPrice;
+    /**
+     * Inclusive epoch ms this revision takes effect: it prices every sample at or
+     * after that instant. `undefined` on a model's base revision, which also
+     * covers every earlier instant.
+     */
+    effectiveFrom?: number;
+}
+/** Resolved pricing for one model: its published rate revisions, oldest first. */
+export interface DeepSeekModelPricing {
+    /** Peak-hour price of the newest revision (the rates in effect now). */
+    peak: DeepSeekTokenPrice;
+    /** Off-peak price of the newest revision (the rates in effect now). */
+    offPeak: DeepSeekTokenPrice;
+    /**
+     * Every published revision of this model, ascending by `effectiveFrom` (an
+     * undated base revision first); always at least one. {@link priceUsage} picks
+     * the revision in effect at the priced sample's own timestamp.
+     */
+    revisions: readonly DeepSeekRateRevision[];
 }
 /** One model's pricing-table row in configuration form. */
-export interface BillingConfigModel {
+export interface BillingConfigModel extends DeepSeekRateRevision {
     /** Wire model id. */
     model: string;
-    /** Peak-hour price. */
-    peak: DeepSeekTokenPrice;
-    /** Off-peak price. */
-    offPeak: DeepSeekTokenPrice;
 }
 /** One peak-hour window on a 24h Beijing-time clock, applied weekdays only. */
 export interface PeakHourWindow {
@@ -53,7 +74,11 @@ export interface BillingConfig {
      * only; weekends (Saturday and Sunday) are always off-peak.
      */
     peakHours?: PeakHourWindow[];
-    /** Per-model pricing rows; omission uses the V4 Flash, V4 Pro, and V4 Flash Vision defaults. */
+    /**
+     * Per-model pricing rows; omission uses the published V4 and MiMo rates.
+     * Several rows for one model declare that model's rate history, priced per
+     * sample by `effectiveFrom` (see {@link BillingConfigModel}).
+     */
     models?: BillingConfigModel[];
 }
 /**
@@ -61,12 +86,30 @@ export interface BillingConfig {
  * applied on weekdays (Monday–Friday) only — weekends are always off-peak
  * (effective 2026-08-23).
  */
-export declare const DEFAULT_PEAK_HOURS: {
-    start: number;
-    end: number;
-}[];
-/** Official peak/off-peak rates (CNY per 1M tokens), effective 2026-08-17. */
-export declare const DEFAULT_MODEL_PRICING: BillingConfigModel[];
+export declare const DEFAULT_PEAK_HOURS: readonly PeakHourWindow[];
+/**
+ * Inclusive epoch ms of the published V4 Flash series re-pricing:
+ * 2026-09-10 12:00 Beijing time (UTC+8, no DST) = 04:00 UTC. Samples before
+ * this instant keep the base rates; samples at or after it bill at the second
+ * revision.
+ */
+export declare const FLASH_SERIES_RATE_CHANGE_AT: number;
+/**
+ * Inclusive epoch ms of the announced V4 Pro route switch: 2026-09-14 12:00
+ * Beijing time (UTC+8, no DST) = 04:00 UTC. From that instant the V4 Pro route
+ * is served by V4.1 Flash and billed at the V4.1 Flash rates.
+ */
+export declare const V4_PRO_ROUTE_SWITCH_AT: number;
+/**
+ * Official peak/off-peak rates (CNY per 1M tokens) per model, as dated
+ * revisions. Base rows are the schedule effective 2026-08-17; the V4 Flash
+ * series (V4.1 Flash, V4 Flash, V4 Flash Vision Exp) carries the second
+ * revision effective 2026-09-10 12:00 Beijing, and the V4 Pro row the V4.1
+ * Flash rates from its announced route switch (2026-09-14 12:00 Beijing) —
+ * the MiMo-V2.5 series is untouched by either adjustment. Rows sharing a model
+ * are that model's rate history.
+ */
+export declare const DEFAULT_MODEL_PRICING: readonly BillingConfigModel[];
 /** Resolved billing configuration: a pricing table plus peak-hour windows. */
 export interface ResolvedBilling {
     peakHours: readonly {
@@ -81,10 +124,43 @@ export interface ResolvedBilling {
  * `z.array` as `[]` rather than `undefined`, so emptiness — not just absence —
  * selects the defaults. Explicit non-empty rows override the same model; a
  * supplied non-empty `models` list is authoritative.
+ *
+ * Rows sharing a model are that model's rate revisions, kept in ascending
+ * `effectiveFrom` order (an undated base revision first). Two rows declaring
+ * the same effective instant are one revision and the later row wins — the
+ * historical override rule — so re-declaring a model can neither duplicate a
+ * revision nor install a second undated base.
  * @param config - optional raw billing configuration.
- * @returns the resolved table and peak-hour windows.
+ * @returns the resolved table (per model: its revisions plus the newest rates) and peak-hour windows.
  */
 export declare function resolveBilling(config: BillingConfig | undefined): ResolvedBilling;
+/** One shifted-timestamp view of a Beijing (UTC+8, no DST) instant. */
+export interface BeijingParts {
+    /**
+     * The instant in epoch milliseconds. Pricing needs it back to resolve the
+     * rate revision in effect at the sample's own timestamp (see
+     * {@link ratesAt}), so the view carries it instead of a second parse.
+     */
+    time: number;
+    /** Beijing hour, `0`–`23`. */
+    hour: number;
+    /** Beijing weekday as `getUTCDay()`: `0` is Sunday, `6` is Saturday. */
+    weekday: number;
+    /** Beijing calendar-day key (`YYYY-MM-DD`). */
+    dayKey: string;
+}
+/**
+ * Derive the Beijing hour, weekday, and calendar-day key of one timestamp with
+ * pure integer arithmetic — every timezone-sensitive read shares this one
+ * implementation, so the pieces cannot drift apart. Callers that filter by
+ * day and then price the same event reuse the returned view, so each event is
+ * parsed exactly once. (The hot fold path runs this per committed event; the
+ * previous `Date` + `toISOString().slice()` version allocated a `Date` and a
+ * 24-character string per call.)
+ * @param time - epoch milliseconds.
+ * @throws {RangeError} when `time` is not a finite number.
+ */
+export declare function beijingPartsOf(time: number): BeijingParts;
 /** The Beijing (Asia/Shanghai, UTC+8, no DST) calendar-day key of a timestamp. */
 export declare function beijingDayKey(now: Date): string;
 /**
@@ -180,17 +256,43 @@ export interface BillingEventContribution {
 /**
  * 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
+ * only; weekends are off-peak) and the rate revision in effect at its own
+ * timestamp. 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).
+ * timestamp; a model with usage but no pricing row contributes nothing.
  * @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;
+/**
+ * Price one event at the official per-model rates using a precomputed
+ * Beijing-time view — the day-filtering and pricing of one event share a
+ * single timezone parse (see {@link beijingPartsOf}). Semantics are identical
+ * to {@link priceEvent}.
+ * @param parts - the event's Beijing-time view.
+ * @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 priceEventAt(parts: BeijingParts, event: SessionEvent, billing: ResolvedBilling, names: ReadonlyMap<string, string>): BillingEventContribution | undefined;
+/**
+ * Price one provider-reported usage sample for one model at the rates of the
+ * sample's own Beijing-time hour and weekday — the peak or off-peak price of
+ * the rate revision in effect at the sample's own timestamp (a re-priced series
+ * bills its history at the rates that applied then). `undefined` when the model
+ * has no pricing row.
+ * @param parts - the sample's Beijing-time view.
+ * @param usage - the reported token buckets.
+ * @param model - the wire model id the sample belongs to.
+ * @param billing - resolved pricing with peak-hour windows.
+ * @param names - model id → display label.
+ * @returns the priced contribution, or `undefined` when the model has no rate row.
+ */
+export declare function priceUsage(parts: BeijingParts, usage: TokenUsage, model: string, billing: ResolvedBilling, names: ReadonlyMap<string, string>): BillingEventContribution | undefined;
 /** A spend with no priced usage. */
 export declare function emptyTodaySpend(): DeepSeekTodaySpend;
 /**
@@ -209,6 +311,96 @@ export declare class SpendAccumulator {
     /** The folded spend; the accumulator stays usable afterwards. */
     finish(): DeepSeekTodaySpend;
 }
+/** The additive inverse of one spend (pure): used to replace a priced sample. */
+export declare function negateSpend(spend: DeepSeekTodaySpend): DeepSeekTodaySpend;
+/**
+ * Subtract one spend from another (pure). Rows that cancel out completely are
+ * dropped so a replaced sample leaves no zero row behind.
+ * @param target - the spend to subtract from.
+ * @param source - the spend to remove.
+ * @returns the difference.
+ */
+export declare function subtractSpend(target: DeepSeekTodaySpend, source: DeepSeekTodaySpend): DeepSeekTodaySpend;
+/**
+ * One priced attempt sample kept for same-step replacement: DSH can report the
+ * same `(turn, step)` twice (an `assistant/attempt` stream and the
+ * `assistant/message` that assembles from it), and a later sample replaces the
+ * earlier one instead of adding to it. `llm/retry-started` clears the slot, so
+ * a retried attempt adds rather than replaces (both requests were billed).
+ */
+export interface BillingFoldSample {
+    /** Turn of the producing attempt. */
+    turn: number;
+    /** Step of the producing attempt. */
+    step: number;
+    /** Beijing day of the sample's timestamp. */
+    dayKey: string;
+    /** The sample's contribution as a one-row spend (subtracted on replacement). */
+    spend: DeepSeekTodaySpend;
+}
+/**
+ * Plain-JSON fold state of one session's billed spend: the latest priced day,
+ * the whole-session total, the fork boundary, the model of the latest request
+ * (needed to price an `assistant/attempt`, which carries no route), and the
+ * last sample kept for replacement.
+ */
+export interface BillingFoldState {
+    /** Beijing-time calendar-day key of `spend`; `''` for no priced usage. */
+    dayKey: string;
+    /** The spend of the session's latest priced Beijing day (own events only). */
+    spend: DeepSeekTodaySpend;
+    /** The spend of the session's OWN events across every day. */
+    session: DeepSeekTodaySpend;
+    /** Fork-inherited prefix length; events below it belong to the source session. */
+    inheritedEventCount: number;
+    /** Wire model of the latest `request/header`; `''` before the first one. */
+    model: string;
+    /** Latest priced attempt sample, for same-step replacement. */
+    last: BillingFoldSample | null;
+}
+/** The empty fold state for one fork boundary. */
+export declare function emptyBillingFoldState(inheritedEventCount?: number): BillingFoldState;
+/**
+ * Fold one committed event into a session's billed-spend state.
+ *
+ * Priced samples come from `assistant/message` (its own reported usage, or the
+ * stream's last usage chunk) and `assistant/attempt` (the stream's last usage
+ * chunk, priced with the model of the latest `request/header`, since an
+ * attempt carries no route). A sample for the same `(turn, step)` replaces the
+ * previous one; `llm/retry-started` closes the replacement slot so a retried
+ * attempt adds. Every other event is inert and returns the same state
+ * reference.
+ * @param state - the previous fold state.
+ * @param event - the committed event.
+ * @param billing - resolved pricing with peak-hour windows.
+ * @param names - model id → display label.
+ * @returns the next state (the same reference when nothing was priced).
+ */
+export declare function applyBillingEvent(state: BillingFoldState, event: SessionEvent, billing: ResolvedBilling, names: ReadonlyMap<string, string>): BillingFoldState;
+/**
+ * Mutable wrapper over {@link applyBillingEvent} for the pure pricing paths:
+ * feed events in order, read the folded spend.
+ */
+export declare class BillingFolder {
+    private readonly billing;
+    private state;
+    /**
+     * @param billing - resolved pricing with peak-hour windows.
+     * @param catalog - model display rows, in presentation order.
+     * @param inheritedEventCount - fork boundary to skip (default 0).
+     */
+    constructor(billing: ResolvedBilling, catalog: readonly {
+        id: string;
+        name: string;
+    }[], inheritedEventCount?: number);
+    private readonly names;
+    /** Fold one event. */
+    add(event: SessionEvent): void;
+    /** Fold every event, in order. */
+    addAll(events: readonly SessionEvent[]): void;
+    /** The folded state (live reference; do not mutate). */
+    get fold(): BillingFoldState;
+}
 /**
  * Merge one priced event's contribution into an accumulator spend (pure:
  * returns a new spend, never mutates its input).
@@ -226,7 +418,11 @@ export declare function addEventContribution(spend: DeepSeekTodaySpend, priced:
  */
 export declare function mergeTodaySpend(target: DeepSeekTodaySpend, source: DeepSeekTodaySpend): DeepSeekTodaySpend;
 /**
- * Price one session's complete event log at the official per-model rates.
+ * Price one session's complete event log at the official per-model rates,
+ * with DSH's attempt semantics: every provider-reported sample (an
+ * `assistant/message`'s usage, or an `assistant/attempt`'s stream usage)
+ * contributes, a later sample for the same `(turn, step)` replaces the earlier
+ * one, and `llm/retry-started` makes the retried attempt add.
  * @param events - one session's complete event log.
  * @param billing - resolved pricing with peak-hour windows.
  * @param catalog - model display rows, in presentation order.
@@ -241,13 +437,13 @@ export declare function computeSessionSpend(events: readonly SessionEvent[], bil
     name: string;
 }[], startSeq?: number): DeepSeekSessionSpend;
 /**
- * Price one completed Turn's billed usage at the official per-model rates,
- * identified by its closing assistant message id. The turn's events are those
- * between its `turn/start` and `turn/end` (both matched by the message's own
- * turn coordinate); each priced event applies the peak/off-peak table by its
- * Beijing-time hour and weekday. A message that cannot be located, a turn
- * without bracketing `turn/start` / `turn/end` events (for example after
- * compaction), or a session with no priced usage prices to zero.
+ * Price one completed Turn's billed usage, identified by its closing
+ * assistant message id. The turn's events are those between its `turn/start`
+ * and `turn/end` (both matched by the message's own turn coordinate), priced
+ * with the same attempt semantics as {@link computeSessionSpend}. A message
+ * that cannot be located, a turn without bracketing `turn/start` / `turn/end`
+ * events (for example after compaction), or a session with no priced usage
+ * prices to zero.
  * @param events - one session's complete event log.
  * @param billing - resolved pricing with peak-hour windows.
  * @param catalog - model display rows, in presentation order.
@@ -259,10 +455,70 @@ export declare function computeTurnSpend(events: readonly SessionEvent[], billin
     name: string;
 }[], messageId: string): DeepSeekTurnSpend;
 /**
- * Price every event whose Beijing-time calendar day is the day of `now`,
- * aggregating across every session's event log. Events from other Beijing
- * days are ignored, so a caller passes the concatenated logs of all sessions.
- * @param events - every session's complete event log, concatenated.
+ * Incremental single-pass fold of one session's completed-Turn costs, keyed by
+ * the id of every assistant message inside each Turn. Feeding the fold only
+ * the appended tail keeps a growing session's map current in O(new events)
+ * instead of re-scanning the whole log per message.
+ *
+ * Semantics are exactly {@link computeTurnSpend}'s: a Turn is the
+ * `turn/start`..`turn/end` range (matched by the event's own turn coordinate),
+ * every priced event inside it contributes at its own timestamp's rate, and a
+ * message outside any bracket contributes nothing.
+ */
+export declare class SessionTurnSpendFolder {
+    private readonly billing;
+    private readonly catalog;
+    private readonly rows;
+    private ids;
+    /** Events of the open Turn, folded with the shared attempt semantics on close. */
+    private events;
+    private open;
+    /** Events already fed; a shorter log resets the fold. */
+    private cursor;
+    /**
+     * @param billing - resolved pricing with peak-hour windows.
+     * @param catalog - model display rows, in presentation order.
+     */
+    constructor(billing: ResolvedBilling, catalog: readonly {
+        id: string;
+        name: string;
+    }[]);
+    /** How many events have been folded so far (the host's incremental cursor). */
+    get processed(): number;
+    /**
+     * Fold every event from the cursor to the end of the log. A log shorter than
+     * the cursor (rewritten session) restarts the fold from an empty state.
+     * @param events - the session's complete event log, in seq order.
+     */
+    feed(events: readonly SessionEvent[]): void;
+    /** The folded map; the fold stays usable afterwards. */
+    finish(): DeepSeekSessionTurnSpends;
+    /** Drop the fold state so the next feed starts from the log's beginning. */
+    private reset;
+}
+/**
+ * Price every completed Turn of one session in a single pass (the pure
+ * equivalent of {@link SessionTurnSpendFolder}).
+ * @param events - one session's complete event log.
+ * @param billing - resolved pricing with peak-hour windows.
+ * @param catalog - model display rows, in presentation order.
+ * @returns one row per assistant message inside a completed Turn, in log order.
+ */
+export declare function computeSessionTurnSpends(events: readonly SessionEvent[], billing: ResolvedBilling, catalog: readonly {
+    id: string;
+    name: string;
+}[]): DeepSeekSessionTurnSpends;
+/**
+ * Price one session's log for the Beijing-time calendar day of `now`. Events
+ * after the reference day are ignored; the fold's latest-day state then
+ * answers the query exactly (empty when the session's latest priced day is not
+ * the reference day). Pricing follows {@link applyBillingEvent} (attempt
+ * samples with same-step replacement).
+ *
+ * The fold's `(turn, step)` replacement slot is per session, so callers must
+ * pass ONE session's log; aggregate across sessions with
+ * {@link mergeTodaySpend}.
+ * @param events - one session's complete event log.
  * @param billing - resolved pricing with peak-hour windows.
  * @param catalog - model display rows, in presentation order.
  * @param now - the reference moment whose Beijing-time calendar day is "today".