usage-tab 1.0.0 → 1.2.0

package/dist/index.d.cts

@@ -154,7 +154,7 @@ type ModelMatchKind = 'override' | 'canonical-qualified' | 'alias-scoped' | 'ali
  * Verify:     pnpm exec tsx scripts/generate-model-registry.ts --check
  */
 
-declare const REGISTRY_VERSION = "registry-5af85ce1a47be918";
+declare const REGISTRY_VERSION = "registry-e5f4ec7eb681a235";
 declare const MODEL_REGISTRY: readonly ModelDescriptor[];
 
 /**
@@ -201,7 +201,18 @@ interface PriceRequest {
     readonly usage: LlmUsage | unknown;
     /** `'batch'` applies the resolved period's `batchMultiplier` when one is published; falls back to standard pricing (with a warning) otherwise. */
     readonly mode?: PriceMode;
-    /** Effective date for pricing-period selection. Defaults to `new Date()`. */
+    /**
+     * Effective date for pricing-period selection. Defaults to `new Date()`.
+     *
+     * Pricing periods start at UTC midnight, so every ISO string form is read
+     * as UTC: an ISO date (`'2026-09-01'`) and an offset-carrying datetime
+     * (`'2026-09-01T05:00:00Z'`) already are, and one *without* an offset
+     * (`'2026-09-01T05:00:00'` — a log timestamp, a `datetime-local` input,
+     * several DB drivers) is read as UTC too, rather than in whatever timezone
+     * the process happens to run. A non-ISO string (`'2026/09/01'`,
+     * `'September 1, 2026'`) is implementation-defined and local in practice —
+     * pass a `Date` or an ISO form instead.
+     */
     readonly at?: Date | string;
 }
 interface CostLine {
@@ -323,6 +334,32 @@ interface CustomPriceInput {
     readonly observedAt?: string;
     readonly notes?: readonly string[];
 }
+/**
+ * An exact running total over one or more `CostBreakdown`s — see
+ * `createCostAggregator`.
+ */
+interface CostTotal {
+    /** How many breakdowns this total covers. */
+    readonly count: number;
+    /** Ergonomic numeric total. Not the authoritative value — see `totalUsdExact`. */
+    readonly totalUsd: number;
+    /** Exact decimal string total, summed with the same fixed-point arithmetic each individual cost was computed with. */
+    readonly totalUsdExact: string;
+    /**
+     * Every distinct `registryVersion` the aggregated breakdowns were priced
+     * against, sorted. More than one means the total mixes pricing snapshots —
+     * expected for a report spanning a registry update, a bug for a total meant
+     * to be reproducible against a single one.
+     */
+    readonly registryVersions: readonly string[];
+}
+interface CostAggregator {
+    /** Adds one breakdown to the running totals. Throws `InvalidRateError` if its `totalUsdExact` is not a non-negative decimal string. */
+    add(breakdown: CostBreakdown): void;
+    total(): CostTotal;
+    /** Per-model totals, keyed `` `${provider}:${canonicalModel}` `` — the resolved identity, so two aliases of one model share a bucket. */
+    byModel(): ReadonlyMap<string, CostTotal>;
+}
 
 declare function calculateCost(request: PriceRequest, options?: PriceOptions): CostBreakdown;
 
@@ -345,6 +382,32 @@ declare function createPriceCalculator(defaults?: PriceCalculatorOptions): Price
  */
 declare function createPriceOverride(input: CustomPriceInput): ModelDescriptor;
 
+/**
+ * Exact sum of decimal USD strings — `totalUsdExact`/`costUsdExact` values,
+ * or any string in the same non-negative decimal format. Returns a decimal
+ * string in that same format (`"0.00"` for an empty list).
+ *
+ * Throws `InvalidRateError` (`INVALID_RATE`) for anything that is not a
+ * non-negative decimal string, rather than coercing it: a stringified
+ * `NaN`, a float-formatted `"1e-7"`, or a `number` that slipped past a
+ * `readonly string[]` at the type level are all silent under-reporting
+ * waiting to happen.
+ */
+declare function sumExactUsd(values: readonly string[]): string;
+/**
+ * Accumulates `CostBreakdown`s into exact running totals — overall and per
+ * `provider:canonicalModel`. Sums are kept as exact fixed-point amounts, so
+ * memory does not grow with the number of breakdowns added; only the number
+ * of distinct models does.
+ *
+ * `total().registryVersions` carries the aggregate's provenance: more than
+ * one entry means the total mixes pricing snapshots, which is legitimate for
+ * a historical report spanning a registry update and a bug for a total that
+ * was supposed to be priced against one snapshot. This package cannot tell
+ * the two apart, so it reports rather than warns.
+ */
+declare function createCostAggregator(): CostAggregator;
+
 /**
  * Stable error types this package throws directly. `resolveModel` and
  * `calculateCost` also propagate `AmbiguousAliasError`, `UnknownModelError`,
@@ -417,4 +480,4 @@ declare function normalizeGoogleUsage(value: unknown): NormalizedUsageResult;
 
 declare function normalizeOpenAICompatibleUsage(value: unknown): NormalizedUsageResult;
 
-export { AmbiguousAliasError, type CostBreakdown, type CostLine, type CustomPriceInput, InvalidLookupDateError, InvalidRateError, InvalidTokenCountError, InvalidUsageError, type LlmUsage, MODEL_REGISTRY, type ModelCandidate, type ModelDescriptor, NoPricingPeriodError, type NormalizedUsageResult, type PriceCalculator, type PriceCalculatorOptions, type PriceMode, type PriceOptions, type PriceRequest, type PriceWarning, type PriceWarningCode, type PricingPeriod, type ProviderId, REGISTRY_VERSION, type RegistrySource, type ResolveModelOptions, type ResolvedModel, UnknownModelError, calculateCost, createPriceCalculator, createPriceOverride, normalizeAnthropicUsage, normalizeGoogleUsage, normalizeOpenAICompatibleUsage, normalizeOpenAIUsage, resolveModel };
+export { AmbiguousAliasError, type CostAggregator, type CostBreakdown, type CostLine, type CostTotal, type CustomPriceInput, InvalidLookupDateError, InvalidRateError, InvalidTokenCountError, InvalidUsageError, type LlmUsage, MODEL_REGISTRY, type ModelCandidate, type ModelDescriptor, NoPricingPeriodError, type NormalizedUsageResult, type PriceCalculator, type PriceCalculatorOptions, type PriceMode, type PriceOptions, type PriceRequest, type PriceWarning, type PriceWarningCode, type PricingPeriod, type ProviderId, REGISTRY_VERSION, type RegistrySource, type ResolveModelOptions, type ResolvedModel, UnknownModelError, calculateCost, createCostAggregator, createPriceCalculator, createPriceOverride, normalizeAnthropicUsage, normalizeGoogleUsage, normalizeOpenAICompatibleUsage, normalizeOpenAIUsage, resolveModel, sumExactUsd };

package/dist/index.d.ts

@@ -154,7 +154,7 @@ type ModelMatchKind = 'override' | 'canonical-qualified' | 'alias-scoped' | 'ali
  * Verify:     pnpm exec tsx scripts/generate-model-registry.ts --check
  */
 
-declare const REGISTRY_VERSION = "registry-5af85ce1a47be918";
+declare const REGISTRY_VERSION = "registry-e5f4ec7eb681a235";
 declare const MODEL_REGISTRY: readonly ModelDescriptor[];
 
 /**
@@ -201,7 +201,18 @@ interface PriceRequest {
     readonly usage: LlmUsage | unknown;
     /** `'batch'` applies the resolved period's `batchMultiplier` when one is published; falls back to standard pricing (with a warning) otherwise. */
     readonly mode?: PriceMode;
-    /** Effective date for pricing-period selection. Defaults to `new Date()`. */
+    /**
+     * Effective date for pricing-period selection. Defaults to `new Date()`.
+     *
+     * Pricing periods start at UTC midnight, so every ISO string form is read
+     * as UTC: an ISO date (`'2026-09-01'`) and an offset-carrying datetime
+     * (`'2026-09-01T05:00:00Z'`) already are, and one *without* an offset
+     * (`'2026-09-01T05:00:00'` — a log timestamp, a `datetime-local` input,
+     * several DB drivers) is read as UTC too, rather than in whatever timezone
+     * the process happens to run. A non-ISO string (`'2026/09/01'`,
+     * `'September 1, 2026'`) is implementation-defined and local in practice —
+     * pass a `Date` or an ISO form instead.
+     */
     readonly at?: Date | string;
 }
 interface CostLine {
@@ -323,6 +334,32 @@ interface CustomPriceInput {
     readonly observedAt?: string;
     readonly notes?: readonly string[];
 }
+/**
+ * An exact running total over one or more `CostBreakdown`s — see
+ * `createCostAggregator`.
+ */
+interface CostTotal {
+    /** How many breakdowns this total covers. */
+    readonly count: number;
+    /** Ergonomic numeric total. Not the authoritative value — see `totalUsdExact`. */
+    readonly totalUsd: number;
+    /** Exact decimal string total, summed with the same fixed-point arithmetic each individual cost was computed with. */
+    readonly totalUsdExact: string;
+    /**
+     * Every distinct `registryVersion` the aggregated breakdowns were priced
+     * against, sorted. More than one means the total mixes pricing snapshots —
+     * expected for a report spanning a registry update, a bug for a total meant
+     * to be reproducible against a single one.
+     */
+    readonly registryVersions: readonly string[];
+}
+interface CostAggregator {
+    /** Adds one breakdown to the running totals. Throws `InvalidRateError` if its `totalUsdExact` is not a non-negative decimal string. */
+    add(breakdown: CostBreakdown): void;
+    total(): CostTotal;
+    /** Per-model totals, keyed `` `${provider}:${canonicalModel}` `` — the resolved identity, so two aliases of one model share a bucket. */
+    byModel(): ReadonlyMap<string, CostTotal>;
+}
 
 declare function calculateCost(request: PriceRequest, options?: PriceOptions): CostBreakdown;
 
@@ -345,6 +382,32 @@ declare function createPriceCalculator(defaults?: PriceCalculatorOptions): Price
  */
 declare function createPriceOverride(input: CustomPriceInput): ModelDescriptor;
 
+/**
+ * Exact sum of decimal USD strings — `totalUsdExact`/`costUsdExact` values,
+ * or any string in the same non-negative decimal format. Returns a decimal
+ * string in that same format (`"0.00"` for an empty list).
+ *
+ * Throws `InvalidRateError` (`INVALID_RATE`) for anything that is not a
+ * non-negative decimal string, rather than coercing it: a stringified
+ * `NaN`, a float-formatted `"1e-7"`, or a `number` that slipped past a
+ * `readonly string[]` at the type level are all silent under-reporting
+ * waiting to happen.
+ */
+declare function sumExactUsd(values: readonly string[]): string;
+/**
+ * Accumulates `CostBreakdown`s into exact running totals — overall and per
+ * `provider:canonicalModel`. Sums are kept as exact fixed-point amounts, so
+ * memory does not grow with the number of breakdowns added; only the number
+ * of distinct models does.
+ *
+ * `total().registryVersions` carries the aggregate's provenance: more than
+ * one entry means the total mixes pricing snapshots, which is legitimate for
+ * a historical report spanning a registry update and a bug for a total that
+ * was supposed to be priced against one snapshot. This package cannot tell
+ * the two apart, so it reports rather than warns.
+ */
+declare function createCostAggregator(): CostAggregator;
+
 /**
  * Stable error types this package throws directly. `resolveModel` and
  * `calculateCost` also propagate `AmbiguousAliasError`, `UnknownModelError`,
@@ -417,4 +480,4 @@ declare function normalizeGoogleUsage(value: unknown): NormalizedUsageResult;
 
 declare function normalizeOpenAICompatibleUsage(value: unknown): NormalizedUsageResult;
 
-export { AmbiguousAliasError, type CostBreakdown, type CostLine, type CustomPriceInput, InvalidLookupDateError, InvalidRateError, InvalidTokenCountError, InvalidUsageError, type LlmUsage, MODEL_REGISTRY, type ModelCandidate, type ModelDescriptor, NoPricingPeriodError, type NormalizedUsageResult, type PriceCalculator, type PriceCalculatorOptions, type PriceMode, type PriceOptions, type PriceRequest, type PriceWarning, type PriceWarningCode, type PricingPeriod, type ProviderId, REGISTRY_VERSION, type RegistrySource, type ResolveModelOptions, type ResolvedModel, UnknownModelError, calculateCost, createPriceCalculator, createPriceOverride, normalizeAnthropicUsage, normalizeGoogleUsage, normalizeOpenAICompatibleUsage, normalizeOpenAIUsage, resolveModel };
+export { AmbiguousAliasError, type CostAggregator, type CostBreakdown, type CostLine, type CostTotal, type CustomPriceInput, InvalidLookupDateError, InvalidRateError, InvalidTokenCountError, InvalidUsageError, type LlmUsage, MODEL_REGISTRY, type ModelCandidate, type ModelDescriptor, NoPricingPeriodError, type NormalizedUsageResult, type PriceCalculator, type PriceCalculatorOptions, type PriceMode, type PriceOptions, type PriceRequest, type PriceWarning, type PriceWarningCode, type PricingPeriod, type ProviderId, REGISTRY_VERSION, type RegistrySource, type ResolveModelOptions, type ResolvedModel, UnknownModelError, calculateCost, createCostAggregator, createPriceCalculator, createPriceOverride, normalizeAnthropicUsage, normalizeGoogleUsage, normalizeOpenAICompatibleUsage, normalizeOpenAIUsage, resolveModel, sumExactUsd };