usage-tab 1.0.0 → 1.2.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,27 +432,80 @@ 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
 `effectiveTo`) date. `calculateCost`'s `at` picks the period active on that
-date — `claude-sonnet-5`'s real introductory rate is the mandated golden
-fixture for this behavior:
+date - `gemini-3.6-flash`'s real promotional rate, whose start and end
+Google publishes, is the golden fixture for this behavior:
 
 ```ts
 import { calculateCost } from 'usage-tab';
 
 const usage = { inputTokens: 1_000_000, outputTokens: 1_000_000 };
 
-calculateCost({ model: 'claude-sonnet-5', provider: 'anthropic', usage, at: '2026-08-15' })
+calculateCost({ model: 'gemini-3.6-flash', provider: 'google', usage, at: '2026-11-01' })
   .totalUsdExact;
-// "12.00" — the introductory rate ($2.00/$10.00), active through 2026-08-31
+// "4.50" - the promotional rate ($0.75/$3.75), published as running through 2026-12-31
 
-calculateCost({ model: 'claude-sonnet-5', provider: 'anthropic', usage, at: '2026-09-15' })
+calculateCost({ model: 'gemini-3.6-flash', provider: 'google', usage, at: '2027-01-15' })
   .totalUsdExact;
-// "18.00" — the standard rate ($3.00/$15.00), effective 2026-09-01
+// "9.00" - the standard rate ($1.50/$7.50), resuming 2027-01-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