@shi-yangyang/dsh-token-dashboard 0.0.0-stage → 0.2.0

package/lib/shared/builtin-prices.js

@@ -0,0 +1,111 @@
+/**
+ * Built-in list prices, per one million tokens, in USD.
+ *
+ * DeepSeek rates are the official peak-hour prices published on 2026-10-30:
+ * off-peak is half. Other entries mirror the public OpenRouter model list.
+ * They are estimates, not a provider invoice, and the user can override any
+ * rate in the dashboard.
+ */
+import { GENERATED_PRICES, GENERATED_PRICE_UPDATED } from './builtin-prices.generated.js';
+export const BUILTIN_PRICE_UPDATED = GENERATED_PRICE_UPDATED;
+export const BUILTIN_PRICE_SOURCE = 'DeepSeek official + OpenRouter snapshot';
+export const BUILTIN_PRICES = [
+    {
+        id: 'deepseek-flash',
+        aliases: [
+            'deepseek-v4.1-flash',
+            'deepseek-v4.1-flash-1017',
+            'deepseek-v4-flash',
+            'deepseek-v4.1-flash-vision-exp',
+            'deepseek-chat',
+        ],
+        price: { currency: 'USD', input: 0.3, output: 1.2, cacheRead: 0.006, cacheWrite: 0 },
+    },
+    {
+        id: 'deepseek-v4-pro',
+        aliases: [
+            'deepseek-v4-pro-0813',
+            'deepseek-v4.1-pro',
+            'deepseek-v4',
+            'deepseek-pro',
+            'deepseek-reasoner',
+        ],
+        price: { currency: 'USD', input: 1.32, output: 3.96, cacheRead: 0.044, cacheWrite: 0 },
+    },
+];
+const ALIASES = {
+    'deepseek-v4.1-flash': 'deepseek-flash',
+    'deepseek-v4.1-flash-1017': 'deepseek-flash',
+    'deepseek-v4-flash': 'deepseek-flash',
+    'deepseek-v4.1-flash-vision-exp': 'deepseek-flash',
+    'deepseek-chat': 'deepseek-flash',
+    'deepseek-v4-pro-0813': 'deepseek-v4-pro',
+    'deepseek-v4.1-pro': 'deepseek-v4-pro',
+    'deepseek-v4': 'deepseek-v4-pro',
+    'deepseek-pro': 'deepseek-v4-pro',
+    'deepseek-reasoner': 'deepseek-v4-pro',
+};
+/**
+ * Every useful lookup form for one model id: the raw id, the id without its
+ * vendor prefix, without a `:free`/`:batch` variant tag, without a trailing
+ * date stamp, and the canonical alias.
+ */
+export function modelKeyCandidates(model) {
+    const raw = model.trim().toLowerCase();
+    if (raw === '')
+        return [];
+    const values = new Set([raw]);
+    const add = (value) => {
+        if (value !== '')
+            values.add(value);
+    };
+    add(raw.replace(/^[^/]+\//, ''));
+    for (const value of [...values]) {
+        const clean = value.replace(/:(free|batch)$/, '');
+        add(clean);
+        add(clean
+            .replace(/[-_](20\d{2})[-_]?(\d{2})[-_]?(\d{2})$/, '')
+            .replace(/[-_](\d{8})$/, '')
+            .replace(/[-_](\d{4})$/, ''));
+    }
+    for (const value of [...values]) {
+        const alias = ALIASES[value];
+        if (alias !== undefined)
+            add(alias);
+    }
+    return [...values];
+}
+const BUILTIN_BY_KEY = new Map();
+// Hand-maintained DeepSeek aliases and official rates win over the generated
+// OpenRouter snapshot; generated entries then fill every other model.
+for (const entry of BUILTIN_PRICES) {
+    for (const key of [entry.id, ...entry.aliases]) {
+        for (const candidate of modelKeyCandidates(key)) {
+            if (!BUILTIN_BY_KEY.has(candidate))
+                BUILTIN_BY_KEY.set(candidate, entry.price);
+        }
+    }
+}
+for (const entry of GENERATED_PRICES) {
+    for (const candidate of modelKeyCandidates(entry.id)) {
+        if (!BUILTIN_BY_KEY.has(candidate))
+            BUILTIN_BY_KEY.set(candidate, entry.price);
+    }
+}
+/** Resolve a built-in list price by model id, ignoring provider/date variants. */
+export function builtinPriceFor(model) {
+    for (const key of modelKeyCandidates(model)) {
+        const price = BUILTIN_BY_KEY.get(key);
+        if (price !== undefined)
+            return { ...price };
+    }
+    return undefined;
+}
+/** Prefer standard entries over batch and free variants when both match. */
+export function modelVariantRank(id) {
+    if (id.includes(':free'))
+        return 2;
+    if (id.includes(':batch'))
+        return 1;
+    return 0;
+}

package/lib/shared/dates.d.ts

@@ -0,0 +1,23 @@
+/** Calendar helpers. Bucket keys are local-calendar labels, never UTC instants. */
+/** `YYYY-MM-DD` in the host's local time zone. */
+export declare function dayKey(ms: number): string;
+/** `YYYY-MM-DDTHH` in the host's local time zone. */
+export declare function hourKey(ms: number): string;
+/** Today's local calendar date. */
+export declare function todayKey(now?: number): string;
+/** The process's IANA time zone, or `UTC` when the runtime cannot report one. */
+export declare function currentTimezone(): string;
+/** Shift a calendar key by a whole number of days. */
+export declare function addDays(key: string, delta: number): string;
+/** Inclusive list of calendar keys from `from` to `to` (bounded by caller). */
+export declare function enumerateDays(from: string, to: string, max?: number): string[];
+/** The trailing `count` calendar keys ending at `today`, ascending. */
+export declare function lastDays(today: string, count: number): string[];
+/** All 24 hour keys for one calendar day, ascending. */
+export declare function dayHours(today: string): string[];
+/** Whole days between two calendar keys, at least 1. */
+export declare function spanDays(from: string, to: string): number;
+/** Validate a `YYYY-MM-DD` string and its calendar meaning. */
+export declare function isDayKey(value: unknown): value is string;
+/** `HH:00` label from an hour bucket key. */
+export declare function hourLabel(key: string): string;

package/lib/shared/dates.js

@@ -0,0 +1,79 @@
+/** Calendar helpers. Bucket keys are local-calendar labels, never UTC instants. */
+/** `YYYY-MM-DD` in the host's local time zone. */
+export function dayKey(ms) {
+    const date = new Date(ms);
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+/** `YYYY-MM-DDTHH` in the host's local time zone. */
+export function hourKey(ms) {
+    const date = new Date(ms);
+    return `${dayKey(ms)}T${pad(date.getHours())}`;
+}
+/** Today's local calendar date. */
+export function todayKey(now = Date.now()) {
+    return dayKey(now);
+}
+/** The process's IANA time zone, or `UTC` when the runtime cannot report one. */
+export function currentTimezone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+    }
+    catch {
+        return 'UTC';
+    }
+}
+/** Shift a calendar key by a whole number of days. */
+export function addDays(key, delta) {
+    const date = new Date(`${key}T12:00:00Z`);
+    date.setUTCDate(date.getUTCDate() + delta);
+    return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}`;
+}
+/** Inclusive list of calendar keys from `from` to `to` (bounded by caller). */
+export function enumerateDays(from, to, max = 400) {
+    const result = [];
+    let cursor = from;
+    for (let index = 0; index <= max; index += 1) {
+        result.push(cursor);
+        if (cursor === to)
+            return result;
+        cursor = addDays(cursor, 1);
+    }
+    return result;
+}
+/** The trailing `count` calendar keys ending at `today`, ascending. */
+export function lastDays(today, count) {
+    const from = addDays(today, -(Math.max(1, count) - 1));
+    return enumerateDays(from, today, Math.max(1, count));
+}
+/** All 24 hour keys for one calendar day, ascending. */
+export function dayHours(today) {
+    const result = [];
+    for (let hour = 0; hour < 24; hour += 1)
+        result.push(`${today}T${pad(hour)}`);
+    return result;
+}
+/** Whole days between two calendar keys, at least 1. */
+export function spanDays(from, to) {
+    const start = Date.parse(`${from}T12:00:00Z`);
+    const end = Date.parse(`${to}T12:00:00Z`);
+    if (!Number.isFinite(start) || !Number.isFinite(end))
+        return 1;
+    return Math.max(1, Math.round((end - start) / 86_400_000) + 1);
+}
+/** Validate a `YYYY-MM-DD` string and its calendar meaning. */
+export function isDayKey(value) {
+    if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const [year, month, day] = value.split('-').map(Number);
+    if (year === undefined || month === undefined || day === undefined)
+        return false;
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+/** `HH:00` label from an hour bucket key. */
+export function hourLabel(key) {
+    return `${key.slice(11, 13)}:00`;
+}
+function pad(value) {
+    return value < 10 ? `0${value}` : String(value);
+}

package/lib/shared/export.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Export helpers. Only aggregated statistics are exported: no prompts,
+ * assistant text, tool arguments, file contents, credentials, or cwd paths.
+ */
+import type { ModelUsage, StatsPayload, TokenBuckets } from './types.js';
+/** Global summary CSV: metrics plus one row per model. */
+export declare function summaryCsv(payload: StatsPayload, models: ModelUsage[], totals: TokenBuckets, rangeLabel: string): string;
+/** Session detail CSV, one row per session, lifetime totals. */
+export declare function sessionsCsv(payload: StatsPayload): string;
+/** Machine-readable Token statistics JSON with cwd fields removed. */
+export declare function statsJson(payload: StatsPayload): string;
+/** Escape one CSV cell, including a formula-injection guard. */
+export declare function csvCell(value: string): string;

package/lib/shared/export.js

@@ -0,0 +1,113 @@
+/**
+ * Export helpers. Only aggregated statistics are exported: no prompts,
+ * assistant text, tool arguments, file contents, credentials, or cwd paths.
+ */
+import { cacheHitRate, totalTokens } from './model.js';
+/** Global summary CSV: metrics plus one row per model. */
+export function summaryCsv(payload, models, totals, rangeLabel) {
+    const total = totalTokens(totals);
+    const rows = [
+        ['Metric', 'Value'],
+        ['Generated At', new Date(payload.generatedAt).toISOString()],
+        ['Range', rangeLabel],
+        ['Timezone', payload.timezone],
+        ['Sessions', String(payload.sessions.total)],
+        ['Sessions With Usage', String(payload.sessions.withUsage)],
+        ['Model Requests', String(payload.requests)],
+        ['Total Tokens', String(total)],
+        ['Uncached Input Tokens', String(totals.uncachedInputTokens)],
+        ['Cache Read Tokens', String(totals.cacheReadTokens)],
+        ['Cache Write Tokens', String(totals.cacheWriteTokens)],
+        ['Output Tokens', String(totals.outputTokens)],
+        ['Cache Hit Rate (%)', (cacheHitRate(totals) * 100).toFixed(2)],
+        [],
+        [
+            'Model',
+            'Provider',
+            'Total Tokens',
+            'Uncached Input Tokens',
+            'Cache Read Tokens',
+            'Cache Write Tokens',
+            'Output Tokens',
+            'Requests',
+            'Share (%)',
+        ],
+    ];
+    for (const model of models) {
+        const modelTotal = totalTokens(model);
+        rows.push([
+            model.model === '' ? 'Unknown' : model.model,
+            model.provider,
+            String(modelTotal),
+            String(model.uncachedInputTokens),
+            String(model.cacheReadTokens),
+            String(model.cacheWriteTokens),
+            String(model.outputTokens),
+            String(model.requests),
+            total === 0 ? '0.00' : ((modelTotal / total) * 100).toFixed(2),
+        ]);
+    }
+    return `${rows.map(row => row.map(csvCell).join(',')).join('\r\n')}\r\n`;
+}
+/** Session detail CSV, one row per session, lifetime totals. */
+export function sessionsCsv(payload) {
+    const rows = [[
+            'Session ID',
+            'Title',
+            'Project',
+            'Models',
+            'Created At',
+            'Last Activity',
+            'Total Tokens',
+            'Uncached Input Tokens',
+            'Cache Read Tokens',
+            'Cache Write Tokens',
+            'Output Tokens',
+            'Requests',
+            'Cache Hit Rate (%)',
+            'Live',
+            'Origin',
+            'Seeded',
+        ]];
+    for (const session of payload.sessionRows) {
+        const models = session.models
+            .map(model => (model.model === '' ? 'Unknown' : model.model))
+            .join('; ');
+        rows.push([
+            session.id,
+            session.title ?? '',
+            session.project,
+            models,
+            new Date(session.createdAt).toISOString(),
+            new Date(session.lastActivity).toISOString(),
+            String(totalTokens(session.totals)),
+            String(session.totals.uncachedInputTokens),
+            String(session.totals.cacheReadTokens),
+            String(session.totals.cacheWriteTokens),
+            String(session.totals.outputTokens),
+            String(session.requests),
+            (session.cacheHitRate * 100).toFixed(2),
+            session.live ? 'yes' : 'no',
+            session.origin,
+            session.seeded ? 'yes' : 'no',
+        ]);
+    }
+    return `${rows.map(row => row.map(csvCell).join(',')).join('\r\n')}\r\n`;
+}
+/** Machine-readable Token statistics JSON with cwd fields removed. */
+export function statsJson(payload) {
+    const sanitized = {
+        ...payload,
+        sessionRows: payload.sessionRows.map(session => ({ ...session, cwd: null })),
+    };
+    return `${JSON.stringify(sanitized, null, 2)}\n`;
+}
+/** Escape one CSV cell, including a formula-injection guard. */
+export function csvCell(value) {
+    let text = value;
+    if (/^[=+\-@\t\r]/.test(text))
+        text = `'${text}`;
+    if (/[",\r\n]/.test(text))
+        return `"${text.replaceAll('"', '""')}"`;
+    return text;
+}

package/lib/shared/format.d.ts

@@ -0,0 +1,23 @@
+/** Presentation helpers. All functions are pure and locale-optional. */
+/** Exact grouped integer. */
+export declare function formatNumber(value: number, locale?: string): string;
+/** Compact token count for cards and axes: 12.4K, 3.1M, 1.2B. */
+export declare function formatCompact(value: number, locale?: string): string;
+/** Ratio in [0,1] rendered as a percentage. */
+export declare function formatPercent(ratio: number, digits?: number): string;
+/** Average output speed; null renders as an em dash. */
+export declare function formatSpeed(value: number | null): string;
+/** Average first-token latency; null renders as an em dash. */
+export declare function formatFirstToken(value: number | null): string;
+/** Local clock time (HH:mm:ss) for the request log. */
+export declare function formatClock(ms: number, locale?: string): string;
+/** Medium date + short time for timestamps. */
+export declare function formatDateTime(ms: number, locale?: string): string;
+/** Short calendar-day label for a `YYYY-MM-DD` bucket key. */
+export declare function formatDayLabel(key: string, locale?: string): string;
+/** `14:00` from a `YYYY-MM-DDTHH` bucket key. */
+export declare function formatHourLabel(key: string): string;
+/** Relative time (e.g. "3 hours ago") with an absolute fallback. */
+export declare function formatRelative(ms: number, now?: number, locale?: string): string;
+/** Width in CSS pixels for a compact size label. */
+export declare function clamp(value: number, min: number, max: number): number;

package/lib/shared/format.js

@@ -0,0 +1,108 @@
+/** Presentation helpers. All functions are pure and locale-optional. */
+/** Exact grouped integer. */
+export function formatNumber(value, locale) {
+    if (!Number.isFinite(value))
+        return '0';
+    return new Intl.NumberFormat(locale, { maximumFractionDigits: 0 }).format(value);
+}
+/** Compact token count for cards and axes: 12.4K, 3.1M, 1.2B. */
+export function formatCompact(value, locale) {
+    if (!Number.isFinite(value) || value === 0)
+        return '0';
+    if (Math.abs(value) < 1_000)
+        return formatNumber(value, locale);
+    try {
+        return new Intl.NumberFormat(locale, {
+            notation: 'compact',
+            compactDisplay: 'short',
+            maximumFractionDigits: value >= 1_000_000 ? 2 : 1,
+        }).format(value);
+    }
+    catch {
+        return formatNumber(value, locale);
+    }
+}
+/** Ratio in [0,1] rendered as a percentage. */
+export function formatPercent(ratio, digits = 1) {
+    if (!Number.isFinite(ratio))
+        return '0%';
+    const value = ratio * 100;
+    const rounded = digits <= 0 ? Math.round(value) : Number(value.toFixed(digits));
+    return `${rounded}%`;
+}
+/** Average output speed; null renders as an em dash. */
+export function formatSpeed(value) {
+    return value === null || !Number.isFinite(value) ? '—' : `≈${Math.round(value)} tok/s`;
+}
+/** Average first-token latency; null renders as an em dash. */
+export function formatFirstToken(value) {
+    return value === null || !Number.isFinite(value) ? '—' : `≈${(value / 1_000).toFixed(1)}s`;
+}
+/** Local clock time (HH:mm:ss) for the request log. */
+export function formatClock(ms, locale) {
+    const date = new Date(ms);
+    if (!Number.isFinite(date.getTime()))
+        return '—';
+    try {
+        return new Intl.DateTimeFormat(locale, { hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false }).format(date);
+    }
+    catch {
+        return date.toISOString().slice(11, 19);
+    }
+}
+/** Medium date + short time for timestamps. */
+export function formatDateTime(ms, locale) {
+    const date = new Date(ms);
+    if (!Number.isFinite(date.getTime()))
+        return '—';
+    try {
+        return new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeStyle: 'short' }).format(date);
+    }
+    catch {
+        return date.toISOString();
+    }
+}
+/** Short calendar-day label for a `YYYY-MM-DD` bucket key. */
+export function formatDayLabel(key, locale) {
+    const date = new Date(`${key}T12:00:00`);
+    if (!Number.isFinite(date.getTime()))
+        return key;
+    try {
+        return new Intl.DateTimeFormat(locale, { month: 'short', day: 'numeric' }).format(date);
+    }
+    catch {
+        return key;
+    }
+}
+/** `14:00` from a `YYYY-MM-DDTHH` bucket key. */
+export function formatHourLabel(key) {
+    return `${key.slice(11, 13)}:00`;
+}
+/** Relative time (e.g. "3 hours ago") with an absolute fallback. */
+export function formatRelative(ms, now = Date.now(), locale) {
+    const delta = ms - now;
+    if (!Number.isFinite(delta))
+        return '—';
+    try {
+        const formatter = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+        const table = [
+            ['year', 365 * 86_400_000],
+            ['month', 30 * 86_400_000],
+            ['day', 86_400_000],
+            ['hour', 3_600_000],
+            ['minute', 60_000],
+        ];
+        for (const [unit, size] of table) {
+            if (Math.abs(delta) >= size)
+                return formatter.format(Math.round(delta / size), unit);
+        }
+        return formatter.format(0, 'second');
+    }
+    catch {
+        return formatDateTime(ms, locale);
+    }
+}
+/** Width in CSS pixels for a compact size label. */
+export function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}

package/lib/shared/model.d.ts

@@ -0,0 +1,37 @@
+/** Token bucket arithmetic shared by Host folding and Client range selection. */
+import type { ModelUsage, TokenBuckets } from './types.js';
+/** Key used when an event carries no reliable provider/model identity. */
+export declare const UNKNOWN_MODEL_KEY = "unknown";
+/** An all-zero bucket set. */
+export declare function emptyBuckets(): TokenBuckets;
+/** Add every field of `source` into `target` in place. */
+export declare function addBuckets(target: TokenBuckets, source: TokenBuckets): void;
+/** The official total: the four disjoint buckets summed, never doubled. */
+export declare function totalTokens(buckets: TokenBuckets): number;
+/** Prompt tokens: uncached input plus both cache directions (no output). */
+export declare function inputTokens(buckets: TokenBuckets): number;
+/** Cache tokens: reads plus writes. */
+export declare function cacheTokens(buckets: TokenBuckets): number;
+/**
+ * Cache hit rate over the prompt side.
+ *
+ * `cacheRead / (uncachedInput + cacheRead + cacheWrite)`, so every prompt
+ * token appears exactly once in the denominator. Zero prompt tokens yield 0.
+ */
+export declare function cacheHitRate(buckets: TokenBuckets): number;
+/** Stable identity key for one provider/model route. */
+export declare function modelKeyOf(provider: string, model: string): string;
+/** Human label for a model row, with the raw id preserved. */
+export declare function modelLabel(usage: Pick<ModelUsage, 'model' | 'provider'>): string;
+/** Clone a bucket set. */
+export declare function cloneBuckets(buckets: TokenBuckets): TokenBuckets;
+/** A new empty mutable model row. */
+export declare function emptyModel(provider: string, model: string): ModelUsage;
+/** Add one sample into a model row in place. */
+export declare function addModelUsage(target: ModelUsage, source: TokenBuckets, requests: number): void;
+/** Sort model rows by total tokens descending, then name. */
+export declare function sortModels(models: ModelUsage[]): ModelUsage[];
+/** Compare two bucket sets field by field. */
+export declare function bucketsEqual(left: TokenBuckets, right: TokenBuckets): boolean;
+/** Subtract every field of `source` from `target` in place. */
+export declare function subtractBuckets(target: TokenBuckets, source: TokenBuckets): void;

package/lib/shared/model.js

@@ -0,0 +1,87 @@
+/** Token bucket arithmetic shared by Host folding and Client range selection. */
+/** Key used when an event carries no reliable provider/model identity. */
+export const UNKNOWN_MODEL_KEY = 'unknown';
+/** An all-zero bucket set. */
+export function emptyBuckets() {
+    return { uncachedInputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, outputTokens: 0 };
+}
+/** Add every field of `source` into `target` in place. */
+export function addBuckets(target, source) {
+    target.uncachedInputTokens += source.uncachedInputTokens;
+    target.cacheReadTokens += source.cacheReadTokens;
+    target.cacheWriteTokens += source.cacheWriteTokens;
+    target.outputTokens += source.outputTokens;
+}
+/** The official total: the four disjoint buckets summed, never doubled. */
+export function totalTokens(buckets) {
+    return buckets.uncachedInputTokens + buckets.cacheReadTokens + buckets.cacheWriteTokens + buckets.outputTokens;
+}
+/** Prompt tokens: uncached input plus both cache directions (no output). */
+export function inputTokens(buckets) {
+    return buckets.uncachedInputTokens + buckets.cacheReadTokens + buckets.cacheWriteTokens;
+}
+/** Cache tokens: reads plus writes. */
+export function cacheTokens(buckets) {
+    return buckets.cacheReadTokens + buckets.cacheWriteTokens;
+}
+/**
+ * Cache hit rate over the prompt side.
+ *
+ * `cacheRead / (uncachedInput + cacheRead + cacheWrite)`, so every prompt
+ * token appears exactly once in the denominator. Zero prompt tokens yield 0.
+ */
+export function cacheHitRate(buckets) {
+    const prompt = inputTokens(buckets);
+    return prompt === 0 ? 0 : buckets.cacheReadTokens / prompt;
+}
+/** Stable identity key for one provider/model route. */
+export function modelKeyOf(provider, model) {
+    if (model === '')
+        return UNKNOWN_MODEL_KEY;
+    return `${provider}::${model}`;
+}
+/** Human label for a model row, with the raw id preserved. */
+export function modelLabel(usage) {
+    if (usage.model === '')
+        return 'Unknown';
+    return usage.model;
+}
+/** Clone a bucket set. */
+export function cloneBuckets(buckets) {
+    return {
+        uncachedInputTokens: buckets.uncachedInputTokens,
+        cacheReadTokens: buckets.cacheReadTokens,
+        cacheWriteTokens: buckets.cacheWriteTokens,
+        outputTokens: buckets.outputTokens,
+    };
+}
+/** A new empty mutable model row. */
+export function emptyModel(provider, model) {
+    return { key: modelKeyOf(provider, model), provider, model, requests: 0, ...emptyBuckets() };
+}
+/** Add one sample into a model row in place. */
+export function addModelUsage(target, source, requests) {
+    addBuckets(target, source);
+    target.requests += requests;
+}
+/** Sort model rows by total tokens descending, then name. */
+export function sortModels(models) {
+    return models.sort((left, right) => {
+        const delta = totalTokens(right) - totalTokens(left);
+        return delta !== 0 ? delta : left.model.localeCompare(right.model);
+    });
+}
+/** Compare two bucket sets field by field. */
+export function bucketsEqual(left, right) {
+    return left.uncachedInputTokens === right.uncachedInputTokens
+        && left.cacheReadTokens === right.cacheReadTokens
+        && left.cacheWriteTokens === right.cacheWriteTokens
+        && left.outputTokens === right.outputTokens;
+}
+/** Subtract every field of `source` from `target` in place. */
+export function subtractBuckets(target, source) {
+    target.uncachedInputTokens -= source.uncachedInputTokens;
+    target.cacheReadTokens -= source.cacheReadTokens;
+    target.cacheWriteTokens -= source.cacheWriteTokens;
+    target.outputTokens -= source.outputTokens;
+}

package/lib/shared/pricing.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Optional cost estimation. Prices are supplied by the user and stored only in
+ * the browser's localStorage; the plugin ships no price table and never infers
+ * a rate. All amounts are labelled "Estimated Cost".
+ */
+import type { ModelUsage, TokenBuckets } from './types.js';
+/** One model's user-configured rates, in `currency` per one million tokens. */
+export interface ModelPrice {
+    currency: string;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+/** Pricing keyed by the same `provider::model` key the usage rows use. */
+export type PricingTable = Record<string, ModelPrice>;
+/** Suggested currencies; the editor accepts any short code as well. */
+export declare const SUGGESTED_CURRENCIES: readonly ["CNY", "USD", "EUR", "JPY"];
+/** A cost row for one model. */
+export interface ModelCostRow {
+    key: string;
+    provider: string;
+    model: string;
+    tokens: TokenBuckets;
+    requests: number;
+    priced: boolean;
+    currency: string | null;
+    amount: number | null;
+    missing: boolean;
+}
+/** Aggregate estimate across models. */
+export interface CostEstimate {
+    rows: ModelCostRow[];
+    totals: Array<{
+        currency: string;
+        amount: number;
+    }>;
+    pricedModels: number;
+    unpricedModels: number;
+}
+/** A fetched online price table plus where and when it came from. */
+export interface OnlinePricingState {
+    prices: PricingTable;
+    source: string;
+    fetchedAt: number;
+}
+/** Resolve user overrides over online prices over built-in list prices. */
+export declare function defaultsForModels(models: readonly Pick<ModelUsage, 'key' | 'model'>[], online: Readonly<PricingTable>): PricingTable;
+/** User overrides win per model; the defaults stay for untouched models. */
+export declare function mergePricing(defaults: PricingTable, overrides: PricingTable): PricingTable;
+/** True when two price rows carry identical currency and rates. */
+export declare function samePrice(left: ModelPrice | undefined, right: ModelPrice | undefined): boolean;
+/** Parse the persisted online table defensively. */
+export declare function parseOnlinePricing(raw: string | null | undefined): OnlinePricingState | null;
+/** Serialize the online table and its provenance. */
+export declare function serializeOnlinePricing(state: OnlinePricingState): string;
+/** True only when every rate and the currency are present and valid. */
+export declare function isPriceConfigured(price: ModelPrice | undefined): price is ModelPrice;
+/** Estimated cost for one model, or null when no usable price exists. */
+export declare function costOf(usage: Pick<TokenBuckets, 'uncachedInputTokens' | 'cacheReadTokens' | 'cacheWriteTokens' | 'outputTokens'>, price: ModelPrice | undefined): number | null;
+/** Build the per-model estimate and currency totals for the current range. */
+export declare function estimateCost(models: ModelUsage[], table: PricingTable): CostEstimate;
+/** Parse a persisted pricing table defensively; unknown or invalid rows are dropped. */
+export declare function parsePricing(raw: string | null | undefined): PricingTable;
+/** Serialize a table for localStorage. */
+export declare function serializePricing(table: PricingTable): string;
+/** Normalize one untrusted pricing value. */
+export declare function normalizePrice(value: unknown): ModelPrice | null;
+/** Format an amount using its currency, with more precision for tiny values. */
+export declare function formatAmount(amount: number, currency: string): string;