@rayadesu/dsh-llm-billing 0.3.16 → 0.3.17

package/lib/types/persistence.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The persistence seams a cold scan reads through. DSH ships a single
+ * persistence runtime family — the handle-based `list` / `open` +
+ * `SessionHandle` surface (0.1.2-alpha.5+, the only one the plugin's
+ * `^0.1.7-alpha.2` peer targets). This module is the only place that knows
+ * the handle shape. Split out of `today-spend.ts` so the scan strategies read
+ * one shape.
+ * @module @rayadesu/dsh-llm-billing/persistence
+ */
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
+import type { SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence';
+import type { SessionLineage } from './session-lineage.ts';
+export interface SessionHeaderSlice extends SessionLineage {
+    /** ≤ 0.1.1-rc.2: the durable fork boundary carried by the header; absent for an unseeded session. */
+    readonly seedLength?: number;
+    /** 0.1.2-alpha.4+: whether the session has a fork-inherited prefix. */
+    readonly isSeeded?: boolean;
+    /**
+     * Durable creation instant (epoch ms). The conversation read uses it to tell
+     * whether a session's spend can span more than the queried day; it is also
+     * part of the projection-cache record identity.
+     */
+    readonly createdAt?: number;
+}
+/**
+ * Structural slice of a live session the scanner reads, accepting both DSH
+ * runtime families: the ≤ 0.1.1-rc.2 baseline exposes the log as
+ * `events` (+ `header.seedLength`), while 0.1.2-alpha.4+ exposes
+ * `snapshotEvents()` and `inheritedEventCount` (and dropped the header field).
+ */
+export interface ScannerSession {
+    readonly id: SessionId;
+    /** ≤ 0.1.1-rc.2: the full event log snapshot. */
+    readonly events?: readonly SessionEvent[];
+    /** 0.1.2-alpha.4+: materialize an immutable log snapshot; no args = the full current log. */
+    snapshotEvents?(fromSeq?: number, toSeqExclusive?: number): readonly SessionEvent[];
+    /** 0.1.2-alpha.4+: the durable inherited-prefix length (0 for an unseeded session). */
+    readonly inheritedEventCount?: number;
+    /** Durable header slice: `seedLength` (older runtime) or `isSeeded` (newer runtime), plus lineage. */
+    readonly header?: SessionHeaderSlice;
+}
+/**
+ * Read one live session's complete event log across both runtime families.
+ * @throws when the session exposes neither the legacy `events` snapshot nor
+ *   the newer `snapshotEvents()` reader — an unknown runtime surface must
+ *   fail loudly rather than silently price an empty log.
+ */
+export declare function liveSessionEvents(session: ScannerSession): readonly SessionEvent[];
+/** Structural slice of a listed persisted session (the snapshot header is a full SessionHeader). */
+export interface ScannerPersistedHeader extends SessionHeaderSlice {
+    readonly id: SessionId;
+    /** Session format generation; part of the projection-cache record identity. */
+    readonly version?: number;
+    /** Working directory recorded on the header; part of the projection-cache record identity. */
+    readonly cwd?: string;
+}
+/** One stored-session read: the full event log plus the durable inherited boundary. */
+export interface ScannerPersistedRead {
+    readonly events: readonly SessionEvent[];
+    /** Inherited-prefix length (fork seed length); 0 for an unseeded session. */
+    readonly seedLength: number;
+}
+/**
+ * One handle read result across DSH generations. The handle seam first
+ * returned the bare event array; since `9b78f99dec` (2026-09-06, in the
+ * 0.1.5-alpha.1 checkout) it returns `{ eventState, events }`. Both shapes are
+ * accepted so the same build serves the npm alpha line and the checkout.
+ */
+export type ScannerHandleRead = readonly SessionEvent[] | {
+    readonly events: readonly SessionEvent[];
+};
+/**
+ * Unwrap a handle read across both return shapes.
+ * @param read - the handle's read result.
+ * @returns the event array.
+ */
+export declare function handleReadEvents(read: ScannerHandleRead): readonly SessionEvent[];
+/** 0.1.2-alpha.5+ handle-based persistence slice: service-level `list` / `open` + `SessionHandle`. */
+export interface ScannerPersistenceHandle {
+    list(): Promise<readonly {
+        header: ScannerPersistedHeader;
+        revision: SessionPersistenceRevision;
+    }[]>;
+    open(id: SessionId, access: 'read'): Promise<{
+        readonly header?: SessionHeaderSlice;
+        /** 0.1.2-alpha.5+: the handle carries the exact inherited cut beside the header. */
+        readonly inheritedEventCount?: number;
+        read(): Promise<ScannerHandleRead>;
+        close(): Promise<void>;
+    }>;
+}
+/** The persistence service slice the scanner reads through (handle-based). */
+export type ScannerPersistence = ScannerPersistenceHandle;
+/**
+ * List every stored session snapshot through the handle-based persistence
+ * service (`list`).
+ * @param persistence - the persistence service slice.
+ * @returns one snapshot per stored session.
+ */
+export declare function persistenceListSnapshots(persistence: ScannerPersistence): Promise<readonly {
+    header: ScannerPersistedHeader;
+    revision: SessionPersistenceRevision;
+}[]>;
+/**
+ * Read one stored session's complete event log and durable inherited boundary
+ * through the handle-based persistence service (`open` + handle `read`; the
+ * handle is closed after the read). Throws when the session does not exist.
+ * @param persistence - the persistence service slice.
+ * @param id - the stored session to read.
+ * @returns the session's complete event log plus its inherited-prefix boundary.
+ */
+export declare function persistenceInspect(persistence: ScannerPersistence, id: SessionId): Promise<ScannerPersistedRead>;
+//# sourceMappingURL=persistence.d.ts.map

package/lib/types/persistence.js

@@ -0,0 +1,63 @@
+/**
+ * The persistence seams a cold scan reads through. DSH ships a single
+ * persistence runtime family — the handle-based `list` / `open` +
+ * `SessionHandle` surface (0.1.2-alpha.5+, the only one the plugin's
+ * `^0.1.7-alpha.2` peer targets). This module is the only place that knows
+ * the handle shape. Split out of `today-spend.ts` so the scan strategies read
+ * one shape.
+ * @module @rayadesu/dsh-llm-billing/persistence
+ */
+import { forkBoundaryOf } from "./billing.js";
+/**
+ * Read one live session's complete event log across both runtime families.
+ * @throws when the session exposes neither the legacy `events` snapshot nor
+ *   the newer `snapshotEvents()` reader — an unknown runtime surface must
+ *   fail loudly rather than silently price an empty log.
+ */
+export function liveSessionEvents(session) {
+    if (session.events !== undefined)
+        return session.events;
+    // Optional-call form keeps the receiver bound (snapshotEvents uses `this`).
+    if (session.snapshotEvents !== undefined)
+        return session.snapshotEvents();
+    throw new Error('llm-billing: session log surface is neither Session.events nor Session.snapshotEvents');
+}
+/**
+ * Unwrap a handle read across both return shapes.
+ * @param read - the handle's read result.
+ * @returns the event array.
+ */
+export function handleReadEvents(read) {
+    // `Array.isArray` does not narrow readonly arrays out of a union, so the
+    // branches are asserted explicitly.
+    if (Array.isArray(read))
+        return read;
+    return read.events;
+}
+/**
+ * List every stored session snapshot through the handle-based persistence
+ * service (`list`).
+ * @param persistence - the persistence service slice.
+ * @returns one snapshot per stored session.
+ */
+export function persistenceListSnapshots(persistence) {
+    return persistence.list();
+}
+/**
+ * Read one stored session's complete event log and durable inherited boundary
+ * through the handle-based persistence service (`open` + handle `read`; the
+ * handle is closed after the read). Throws when the session does not exist.
+ * @param persistence - the persistence service slice.
+ * @param id - the stored session to read.
+ * @returns the session's complete event log plus its inherited-prefix boundary.
+ */
+export async function persistenceInspect(persistence, id) {
+    const handle = await persistence.open(id, 'read');
+    try {
+        return { events: handleReadEvents(await handle.read()), seedLength: forkBoundaryOf(handle) };
+    }
+    finally {
+        await handle.close();
+    }
+}
+//# sourceMappingURL=persistence.js.map

package/lib/types/pricing-table.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The published rate schedule: which models cost what, and since when.
+ *
+ * Data only — every policy decision about how a rate is chosen (revision
+ * lookup, peak windows, day boundaries) lives in `billing.ts`. Keeping them
+ * apart means adding a model never touches the pricing engine: the change is
+ * one row here, plus a test.
+ *
+ * Rates are CNY per 1M tokens. Rows sharing a model are that model's rate
+ * history (see {@link resolveBilling}).
+ * @module @rayadesu/dsh-llm-billing/pricing-table
+ */
+import type { BillingConfigModel, PeakHourWindow } from './billing.ts';
+/**
+ * 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[];
+//# sourceMappingURL=pricing-table.d.ts.map

package/lib/types/pricing-table.js

@@ -0,0 +1,118 @@
+/**
+ * The published rate schedule: which models cost what, and since when.
+ *
+ * Data only — every policy decision about how a rate is chosen (revision
+ * lookup, peak windows, day boundaries) lives in `billing.ts`. Keeping them
+ * apart means adding a model never touches the pricing engine: the change is
+ * one row here, plus a test.
+ *
+ * Rates are CNY per 1M tokens. Rows sharing a model are that model's rate
+ * history (see {@link resolveBilling}).
+ * @module @rayadesu/dsh-llm-billing/pricing-table
+ */
+/**
+ * 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 const DEFAULT_PEAK_HOURS = [
+    { start: 9, end: 12 },
+    { start: 14, end: 18 },
+];
+/**
+ * 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 const FLASH_SERIES_RATE_CHANGE_AT = Date.UTC(2026, 8, 10, 4, 0, 0);
+/**
+ * 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 const V4_PRO_ROUTE_SWITCH_AT = Date.UTC(2026, 8, 14, 4, 0, 0);
+/** The V4 Flash series' base rates (effective 2026-08-17), CNY per 1M tokens. */
+const FLASH_BASE_RATES = {
+    peak: { cacheHitInput: 0.10, cacheMissInput: 3.0, output: 9.0 },
+    offPeak: { cacheHitInput: 0.05, cacheMissInput: 1.5, output: 4.5 },
+};
+/**
+ * The V4 Flash series' second revision (effective
+ * {@link FLASH_SERIES_RATE_CHANGE_AT}): off-peak 0.02 / 1.0 / 4.0, peak at
+ * twice those prices.
+ */
+const FLASH_REPRICED_RATES = {
+    effectiveFrom: FLASH_SERIES_RATE_CHANGE_AT,
+    peak: { cacheHitInput: 0.04, cacheMissInput: 2.0, output: 8.0 },
+    offPeak: { cacheHitInput: 0.02, cacheMissInput: 1.0, output: 4.0 },
+};
+/**
+ * The V4.1 Flash rates as they reach the retired V4 Pro route from
+ * {@link V4_PRO_ROUTE_SWITCH_AT}: the same price pair as the flash series'
+ * second revision, carried at its own effective instant.
+ */
+const V4_PRO_SWITCHED_RATES = {
+    effectiveFrom: V4_PRO_ROUTE_SWITCH_AT,
+    peak: FLASH_REPRICED_RATES.peak,
+    offPeak: FLASH_REPRICED_RATES.offPeak,
+};
+/**
+ * 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 const DEFAULT_MODEL_PRICING = [
+    // deepseek-flash is the V4.1 Flash route, DSH's default catalog entry; image
+    // inputs are converted to tokens at the same per-token price.
+    { model: 'deepseek-flash', ...FLASH_BASE_RATES },
+    { model: 'deepseek-flash', ...FLASH_REPRICED_RATES },
+    { model: 'deepseek-v4-flash', ...FLASH_BASE_RATES },
+    { model: 'deepseek-v4-flash', ...FLASH_REPRICED_RATES },
+    // deepseek-v4.1-flash-expires-on-0910 was the V4.1 Flash preview route,
+    // retired when the model was released on 2026-09-10; its rows stay so the
+    // logs that used it keep pricing.
+    { model: 'deepseek-v4.1-flash-expires-on-0910', ...FLASH_BASE_RATES },
+    { model: 'deepseek-v4.1-flash-expires-on-0910', ...FLASH_REPRICED_RATES },
+    {
+        model: 'deepseek-v4-pro',
+        peak: { cacheHitInput: 0.30, cacheMissInput: 9.0, output: 27.0 },
+        offPeak: { cacheHitInput: 0.15, cacheMissInput: 4.5, output: 13.5 },
+    },
+    // From the announced route switch V4 Pro is served by V4.1 Flash and billed
+    // at the V4.1 Flash rates.
+    { model: 'deepseek-v4-pro', ...V4_PRO_SWITCHED_RATES },
+    // deepseek-v4-flash-vision-exp bills at the same rates as deepseek-v4-flash;
+    // images are converted to tokens at the same per-token price.
+    { model: 'deepseek-v4-flash-vision-exp', ...FLASH_BASE_RATES },
+    { model: 'deepseek-v4-flash-vision-exp', ...FLASH_REPRICED_RATES },
+    // MiMo series (Xiaomi): flat rate, no peak/off-peak distinction. V2.6 keeps
+    // V2.5's published API pricing (2026-09-22 launch, "API pricing unchanged
+    // from V2.5"); cache writes bill at the miss rate, though Xiaomi's launch
+    // window makes them free provider-side for a limited time.
+    {
+        model: 'mimo-v2.5-pro',
+        peak: { cacheHitInput: 0.025, cacheMissInput: 3.0, output: 6.0 },
+        offPeak: { cacheHitInput: 0.025, cacheMissInput: 3.0, output: 6.0 },
+    },
+    {
+        model: 'mimo-v2.5',
+        peak: { cacheHitInput: 0.02, cacheMissInput: 1.0, output: 2.0 },
+        offPeak: { cacheHitInput: 0.02, cacheMissInput: 1.0, output: 2.0 },
+    },
+    {
+        model: 'mimo-v2.6-pro',
+        peak: { cacheHitInput: 0.025, cacheMissInput: 3.0, output: 6.0 },
+        offPeak: { cacheHitInput: 0.025, cacheMissInput: 3.0, output: 6.0 },
+    },
+    {
+        model: 'mimo-v2.6-flash',
+        peak: { cacheHitInput: 0.02, cacheMissInput: 1.0, output: 2.0 },
+        offPeak: { cacheHitInput: 0.02, cacheMissInput: 1.0, output: 2.0 },
+    },
+];
+//# sourceMappingURL=pricing-table.js.map

package/lib/types/pricing.d.ts

@@ -0,0 +1,203 @@
+/**
+ * DeepSeek pricing: the peak/off-peak pricing table, the per-event pricing, and
+ * the resolved-billing shape. Pure functions over token usage 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} / {@link priceUsage}; the
+ * fold state machine that consumes it (`BillingFolder` / {@link applyBillingEvent})
+ * lives in `fold.ts`, and every scan path prices through these primitives so a
+ * pricing-table change cannot drift one path from the others.
+ * @module @rayadesu/dsh-llm-billing/pricing
+ */
+import type { TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { BeijingParts } from './beijing-time.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[];
+}
+export { DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, FLASH_SERIES_RATE_CHANGE_AT, V4_PRO_ROUTE_SWITCH_AT } from './pricing-table.ts';
+/** 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;
+/**
+ * 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;
+/** Every token one usage sample reports, whether or not it gets priced. */
+export declare function usageTokens(usage: TokenUsage): number;
+/**
+ * Report a model carrying no rate row, at most once per id (and at most
+ * {@link UNPRICED_WARN_LIMIT} ids per process). Every figure reads as zero when
+ * the upstream model is unknown, which looks exactly like "no usage" rather
+ * than a missing row — the one thing this warning exists to separate.
+ *
+ * Deliberately NOT guessed: model ids are chosen by whoever ships the model, so
+ * a similar-looking name says nothing about a similar price — and a wrong number
+ * that LOOKS authoritative is worse than a visible gap. The fix is one row under
+ * `billing.models`, which is exactly what the warning points at.
+ * @param model - the unlisted wire model id.
+ */
+export declare function reportUnpricedModel(model: string): void;
+/**
+ * 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;
+//# sourceMappingURL=pricing.d.ts.map