usage-tab 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -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

@@ -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.js

@@ -80,8 +80,9 @@ function toCandidate(descriptor) {
 }
 function matchExact(pool, id, provider) {
   if (provider !== void 0) {
-    const canonical = pool.find((d) => d.provider === provider && d.canonicalId === id);
-    if (canonical !== void 0) return { unique: canonical };
+    const canonical = pool.filter((d) => d.provider === provider && d.canonicalId === id);
+    if (canonical.length === 1) return { unique: canonical[0] };
+    if (canonical.length > 1) return { ambiguous: canonical };
     const scoped = pool.filter((d) => d.provider === provider && d.aliases.includes(id));
     if (scoped.length === 1) return { unique: scoped[0] };
     if (scoped.length > 1) return { ambiguous: scoped };
@@ -109,16 +110,22 @@ function resolveModel(requestedId, registry, options = {}) {
     }
   }
   if (provider !== void 0) {
-    const canonical = registry.find(
+    const canonical = registry.filter(
       (d) => d.provider === provider && d.canonicalId === requestedId
     );
-    if (canonical !== void 0) {
-      return {
-        descriptor: canonical,
-        matchedBy: "canonical-qualified",
-        requestedId,
-        requestedProvider: provider
-      };
+    if (canonical.length === 1) {
+      const descriptor = canonical[0];
+      if (descriptor !== void 0) {
+        return {
+          descriptor,
+          matchedBy: "canonical-qualified",
+          requestedId,
+          requestedProvider: provider
+        };
+      }
+    }
+    if (canonical.length > 1) {
+      throw new AmbiguousAliasError(requestedId, canonical.map(toCandidate));
     }
     const scoped = registry.filter(
       (d) => d.provider === provider && d.aliases.includes(requestedId)
@@ -172,10 +179,16 @@ function resolveModel(requestedId, registry, options = {}) {
 }
 
 // ../../internal/model-registry/src/pricing-period.ts
+var OFFSETLESS_ISO_DATETIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?$/;
 function toTimestamp(value) {
-  const ms = value instanceof Date ? value.getTime() : Date.parse(value);
+  if (value instanceof Date) {
+    const ms2 = value.getTime();
+    if (Number.isNaN(ms2)) throw new InvalidLookupDateError(String(value));
+    return ms2;
+  }
+  const ms = Date.parse(OFFSETLESS_ISO_DATETIME.test(value) ? `${value}Z` : value);
   if (Number.isNaN(ms)) {
-    throw new InvalidLookupDateError(value instanceof Date ? value.toISOString() : value);
+    throw new InvalidLookupDateError(value);
   }
   return ms;
 }
@@ -1507,7 +1520,7 @@ var InvalidRateError = class extends Error {
 var ZERO = { numerator: 0n, scale: 0 };
 var DECIMAL_PATTERN = /^\d+(\.\d+)?$/;
 function parseDecimalRate(value, field) {
-  if (!DECIMAL_PATTERN.test(value)) {
+  if (typeof value !== "string" || !DECIMAL_PATTERN.test(value)) {
     throw new InvalidRateError(field, value);
   }
   const dot = value.indexOf(".");
@@ -1941,6 +1954,59 @@ function createPriceOverride(input) {
   };
 }
 
+// src/aggregate.ts
+function sumExactUsd(values) {
+  const amounts = [];
+  for (const [index, value] of values.entries()) {
+    amounts.push(parseDecimalRate(value, `values[${String(index)}]`));
+  }
+  return formatExact(addExact(amounts));
+}
+function modelKey(breakdown) {
+  return `${breakdown.provider}:${breakdown.canonicalModel}`;
+}
+function newBucket() {
+  return { count: 0, sum: ZERO, registryVersions: /* @__PURE__ */ new Set() };
+}
+function accumulate(bucket, amount, registryVersion) {
+  bucket.count += 1;
+  bucket.sum = addExact([bucket.sum, amount]);
+  bucket.registryVersions.add(registryVersion);
+}
+function toTotal(bucket) {
+  return {
+    count: bucket.count,
+    totalUsd: toDisplayNumber(bucket.sum),
+    totalUsdExact: formatExact(bucket.sum),
+    registryVersions: [...bucket.registryVersions].sort()
+  };
+}
+function createCostAggregator() {
+  const overall = newBucket();
+  const byModelBuckets = /* @__PURE__ */ new Map();
+  return {
+    add(breakdown) {
+      const amount = parseDecimalRate(breakdown.totalUsdExact, "totalUsdExact");
+      const key = modelKey(breakdown);
+      let bucket = byModelBuckets.get(key);
+      if (bucket === void 0) {
+        bucket = newBucket();
+        byModelBuckets.set(key, bucket);
+      }
+      accumulate(bucket, amount, breakdown.registryVersion);
+      accumulate(overall, amount, breakdown.registryVersion);
+    },
+    total() {
+      return toTotal(overall);
+    },
+    byModel() {
+      const result = /* @__PURE__ */ new Map();
+      for (const [key, bucket] of byModelBuckets) result.set(key, toTotal(bucket));
+      return result;
+    }
+  };
+}
+
 // src/normalize/openai.ts
 var KNOWN_TOP_LEVEL = /* @__PURE__ */ new Set([
   "prompt_tokens",
@@ -2139,12 +2205,14 @@ export {
   REGISTRY_VERSION,
   UnknownModelError,
   calculateCost,
+  createCostAggregator,
   createPriceCalculator,
   createPriceOverride,
   normalizeAnthropicUsage,
   normalizeGoogleUsage,
   normalizeOpenAICompatibleUsage,
   normalizeOpenAIUsage,
-  resolveModel2 as resolveModel
+  resolveModel2 as resolveModel,
+  sumExactUsd
 };
 //# sourceMappingURL=index.js.map