usage-tab 1.0.0 → 1.1.0

package/README.md

@@ -112,7 +112,10 @@ result.warnings; // readonly PriceWarning[] — empty here, never silently dropp
   version) proves two calculations used byte-identical pricing data.
 - **Historical lookups are exact and reproducible.** A cost computed for a
   specific `at` date always resolves the same pricing period, regardless of
-  when you run it.
+  when — or on which machine — you run it: every ISO `at` string is read as
+  UTC, including the offset-less form `Date.parse` would otherwise read in
+  the host's local timezone. See
+  [Historical lookup](#historical-lookup-and-the-data-freshnesseffective-date-policy).
 - **Zero runtime dependencies, browser-safe.** No `node:` import in `src/`.
 
 ## API
@@ -127,7 +130,7 @@ interface PriceRequest {
   provider?: string; // qualifies resolution to one provider — see "two channels, one rule" below
   usage: LlmUsage | unknown; // normalize a raw provider response first — see below
   mode?: 'standard' | 'batch';
-  at?: Date | string; // defaults to `new Date()`
+  at?: Date | string; // defaults to `new Date()`; an ISO string is read as UTC
 }
 
 interface CostBreakdown {
@@ -429,6 +432,45 @@ result.totalUsdExact; // "0.666666" — exact
 result.totalUsd; // 0.666666    — the same value, as a number
 ```
 
+### Totalling many requests exactly
+
+`sum += breakdown.totalUsd` puts binary floating point back exactly where
+`totalUsdExact` removed it. `createCostAggregator` keeps the running totals
+on the same exact `bigint` path, overall and per model:
+
+```ts
+import { calculateCost, createCostAggregator, sumExactUsd } from 'usage-tab';
+
+const aggregator = createCostAggregator();
+for (const call of [
+  { model: 'gpt-4o', provider: 'openai', usage: { inputTokens: 40_000, outputTokens: 4_000 } },
+  {
+    model: 'claude-sonnet-5',
+    provider: 'anthropic',
+    usage: { inputTokens: 40_000, outputTokens: 4_000 },
+  },
+]) {
+  aggregator.add(calculateCost({ ...call, at: '2026-08-15' }));
+}
+
+aggregator.total().totalUsdExact; // exact decimal string — the value to store
+aggregator.total().count; // 2
+aggregator.byModel(); // Map keyed "openai:gpt-4o", "anthropic:claude-sonnet-5"
+
+// Already have the strings — from a database column, say:
+sumExactUsd(['0.10', '0.20']); // "0.30", where 0.1 + 0.2 gives 0.30000000000000004
+```
+
+`total().registryVersions` lists every pricing snapshot the aggregate drew
+on. More than one is expected for a report spanning a registry update, and a
+bug for a total meant to be reproducible against a single one — this package
+reports it rather than guessing which you meant.
+
+Both throw `InvalidRateError` on a value that is not a non-negative decimal
+string, rather than coercing it: a stringified `NaN` or an exponent-notation
+`"1e-7"` silently summing to something wrong is the failure this exists to
+prevent.
+
 ### Historical lookup and the data-freshness/effective-date policy
 
 Every price carries an `effectiveFrom` (and, when superseded, an
@@ -450,6 +492,20 @@ calculateCost({ model: 'claude-sonnet-5', provider: 'anthropic', usage, at: '202
 // "18.00" — the standard rate ($3.00/$15.00), effective 2026-09-01
 ```
 
+Period boundaries are UTC midnights, so **every ISO `at` string is read as
+UTC**. An ISO date (`'2026-09-01'`) and an offset-carrying datetime
+(`'2026-09-01T05:00:00Z'`, `'...+02:00'`) already are by specification; one
+_without_ an offset — `'2026-09-01T05:00:00'`, the shape a log timestamp, a
+`datetime-local` input, and several DB drivers produce — is `Date.parse`'s
+local-time case, and is read as UTC here too. Otherwise the same lookup
+prices at $12.00 in one deployment and $18.00 in another, purely from the
+host's `TZ`.
+
+A non-ISO string (`'2026/09/01'`, `'September 1, 2026'`) is
+implementation-defined rather than specified, so there is no single reading
+to normalize it to and it keeps whatever `Date.parse` does with it — local
+time, in practice. Pass a `Date` or an ISO form.
+
 Pricing data is committed, not fetched — there is no runtime network call,
 ever. That means it can go stale between releases: a provider can change a
 price the day after `usage-tab` ships, and calculations will use the old

package/dist/index.cjs

@@ -30,13 +30,15 @@ __export(index_exports, {
   REGISTRY_VERSION: () => REGISTRY_VERSION,
   UnknownModelError: () => UnknownModelError,
   calculateCost: () => calculateCost,
+  createCostAggregator: () => createCostAggregator,
   createPriceCalculator: () => createPriceCalculator,
   createPriceOverride: () => createPriceOverride,
   normalizeAnthropicUsage: () => normalizeAnthropicUsage,
   normalizeGoogleUsage: () => normalizeGoogleUsage,
   normalizeOpenAICompatibleUsage: () => normalizeOpenAICompatibleUsage,
   normalizeOpenAIUsage: () => normalizeOpenAIUsage,
-  resolveModel: () => resolveModel2
+  resolveModel: () => resolveModel2,
+  sumExactUsd: () => sumExactUsd
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -122,8 +124,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 };
@@ -151,16 +154,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)
@@ -214,10 +223,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;
 }
@@ -1549,7 +1564,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(".");
@@ -1983,6 +1998,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",