@rayadesu/dsh-llm-billing 0.3.16 → 0.3.18

package/lib/types/billing.d.ts

@@ -1,198 +1,42 @@
 /**
- * DeepSeek billing: the peak/off-peak pricing table and the per-session spend
- * 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.
+ * DeepSeek billing aggregation: the session/turn/today spend computations
+ * over the pricing engine (`pricing.ts`) and the per-event fold state machine
+ * (`fold.ts`). Pure functions over session events, so the whole spend is
+ * testable without a key and the Remote gateway stays transport-free.
  *
- * The per-event pricing lives in {@link priceEvent} and the fold in the
- * {@link SpendAccumulator}: the events-scan paths ({@link computeSessionSpend},
- * {@link computeTodaySpend}), the session-projection unit (`billingTodaySpend`
- * in projection.ts), and the scanner's single-pass events path all price
- * through the same primitives, so a pricing-table change cannot drift one path
- * from the others.
+ * The fold in {@link BillingFolder} / {@link applyBillingEvent} (see `fold.ts`)
+ * and the per-event pricing in `pricing.ts` are the single source of truth the
+ * events-scan paths, the session-projection unit, and the scanner all price
+ * through, so a pricing-table change cannot drift one path 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, DeepSeekSessionTurnSpends, DeepSeekTodaySpend, DeepSeekTurnSpend } from './types.ts';
-/** One token price point, in CNY per 1M tokens. */
-export interface DeepSeekTokenPrice {
-    /** 1M input cache-hit tokens. */
-    cacheHitInput: number;
-    /** 1M input cache-miss tokens (cache writes bill at this rate too). */
-    cacheMissInput: number;
-    /** 1M output tokens. */
-    output: number;
-}
-/**
- * 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 extends DeepSeekRateRevision {
-    /** Wire model id. */
-    model: string;
-}
-/** One peak-hour window on a 24h Beijing-time clock, applied weekdays only. */
-export interface PeakHourWindow {
-    /** Inclusive start hour, `0`–`23`. */
-    start: number;
-    /** Exclusive end hour, `1`–`24`. */
-    end: number;
-}
-/** Optional billing configuration; omission uses the published defaults. */
-export interface BillingConfig {
-    /**
-     * Peak-hour windows in Beijing time, applied on weekdays (Monday–Friday)
-     * only; weekends (Saturday and Sunday) are always off-peak.
-     */
-    peakHours?: PeakHourWindow[];
-    /**
-     * 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[];
-}
-/**
- * Published peak-hour windows (Beijing time): 09:00–12:00 and 14:00–18:00,
- * applied on weekdays (Monday–Friday) only — weekends are always off-peak
- * (effective 2026-08-23).
- */
-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 series (V2.5, and V2.6 which kept V2.5's pricing) 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 {
-        start: number;
-        end: number;
-    }[];
-    models: ReadonlyMap<string, DeepSeekModelPricing>;
-}
-/**
- * Resolve optional configuration to a pricing table, defaulting omitted or
- * empty rows to the published rates. Schemastery materializes an absent
- * `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 (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;
+import type { ResolvedBilling } from './pricing.ts';
+export * from './beijing-time.ts';
+export * from './spend.ts';
+export * from './pricing.ts';
+export * from './fold.ts';
 /**
  * Structural source of a session's durable inherited-prefix boundary. The
- * field moved between DSH runtimes:
- *
- * - since 0.1.2-alpha.4, `SessionHeader.seedLength` was removed (the header
- *   now carries only `isSeeded`: boolean) and the exact cut moved to
- *   `Session.inheritedEventCount` / `SessionInspection.inheritedEventCount`;
- * - at and before the 0.1.1-rc.2 npm baseline, the cut lived on the durable
- *   header as `seedLength` (optional; absent for an unseeded session) and on
- *   the persistence `inspect` result as `meta.seedLength`.
- *
- * The reader accepts any of the three shapes and prefers the newer,
- * exact-count field, so the same plugin code prices correctly on both
- * families of runtime.
+ * exact cut moved between DSH runtimes: since 0.1.2-alpha.4,
+ * `SessionHeader.seedLength` was removed (the header now carries only
+ * `isSeeded`: boolean) and the count moved to `Session.inheritedEventCount` /
+ * `SessionHandle.inheritedEventCount`. The reader prefers that exact-count
+ * field and otherwise falls back to the older `seedLength` on the durable
+ * header, so the same plugin code prices correctly across the live-session
+ * and handle surfaces it still meets.
  */
 export interface ForkBoundarySource {
-    /** 0.1.2-alpha.4+: `Session.inheritedEventCount` / `SessionInspection.inheritedEventCount`. */
+    /** 0.1.2-alpha.4+: `Session.inheritedEventCount` / `SessionHandle.inheritedEventCount`. */
     readonly inheritedEventCount?: number;
-    /** 0.1.1-rc.2 and earlier: `SessionHeader.seedLength`. */
+    /** ≤ 0.1.1-rc.2 live-session header: `SessionHeader.seedLength`. */
     readonly seedLength?: number;
-    /** ≤ 0.1.1-rc.2: the header slice of a `Session` (its `header.seedLength`). */
+    /** Durable header slice of a live session or opened handle (its `seedLength`). */
     readonly header?: {
         readonly seedLength?: number;
         readonly isSeeded?: boolean;
     };
-    /** ≤ 0.1.1-rc.2: the `meta` of a persistence `inspect` result (its `seedLength`). */
-    readonly meta?: {
-        readonly seedLength?: number;
-        readonly isSeeded?: boolean;
-    };
 }
 /**
  * The durable inherited-prefix boundary of one session: the number of leading
@@ -201,222 +45,17 @@ export interface ForkBoundarySource {
  * in its session state; every event with `seq < seedLength` is a copy of an
  * event already billed in that source session, so pricing must skip them or
  * the same model output is counted once per copy. Accepts the durable field
- * of both DSH runtime families (see {@link ForkBoundarySource}).
- * @param source - the session, inspection result, header slice, or durable
- *   header carrying the boundary; `undefined` reads as 0.
+ * of the live-session and handle surfaces (see {@link ForkBoundarySource}).
+ * @param source - the session, header slice, or opened handle carrying the
+ *   boundary; `undefined` reads as 0.
  * @returns the inherited-prefix length; 0 for an unseeded session.
  */
 export declare function forkBoundaryOf(source: ForkBoundarySource | undefined): number;
-/** Whether a durable header marks a fork-inherited (seeded) session across both runtime families. */
+/** Whether a durable header marks a fork-inherited (seeded) session across the live-session and handle surfaces. */
 export declare function isSeededSession(header: {
     readonly seedLength?: number;
     readonly isSeeded?: boolean;
 } | undefined): boolean;
-/**
- * Whether a timestamp falls inside any peak-hour window (Beijing time,
- * weekdays Monday–Friday only). Weekends (Saturday and Sunday) are always
- * off-peak, matching the published peak-hours rule.
- * @param billing - resolved pricing with peak-hour windows.
- * @param now - the moment to classify.
- * @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) 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.
- * @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;
-/**
- * Mutable model-row accumulator behind every spend fold. Rows keep first-seen
- * model order — the same shape a pure `addEventContribution` chain produces —
- * so the single-pass scan path and the pure public paths cannot diverge. One
- * `Map` lookup per contribution instead of a per-event array copy: the huge
- * event-log folds allocate one row object per model, not one intermediate
- * array per event.
- */
-export declare class SpendAccumulator {
-    private readonly rows;
-    private total;
-    /** Add one priced contribution. */
-    add(priced: BillingEventContribution): void;
-    /** 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).
- * @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,
  * with DSH's attempt semantics: every provider-reported sample (an