@trazum/core 2.4.1 → 2.4.3

package/src/types.ts

@@ -203,6 +203,18 @@ export interface PricingTier {
   outputPerMTok: number;
 }
 
+/** One published price this model carried until an instant. See `ModelPricing.history`. */
+export interface PricePeriod {
+  /** ISO 8601 instant, exclusive: a call at exactly this instant is priced by what came after. */
+  until: string;
+  inputPerMTok: number;
+  outputPerMTok: number;
+  /** The conditional rates in force during the period; none means none applied. */
+  tiers?: PricingTier[];
+  /** The cache and batch ratios during the period; absent means the row's own. */
+  multipliers?: CostMultipliers;
+}
+
 export interface ModelPricing {
   id: string;
   displayName: string;
@@ -298,6 +310,22 @@ export interface ModelPricing {
    * and keeps this field optional in effect as well as in the type.
    */
   tiers?: PricingTier[];
+  /**
+   * What this id cost before its current price, earliest period first.
+   *
+   * A usage log is history, and a provider that cuts a price at 04:00 UTC on
+   * a Thursday has billed the same id two ways in one month. One price for
+   * all time priced the older calls at the newer rate, or the newer at the
+   * older, and nothing on screen said which. A call at `on` is priced by the
+   * first period whose `until` is after it; a call at or after the last
+   * `until` takes the fields above. Each period carries its own tiers and
+   * cache ratio, because a provider that reprices usually reprices both.
+   *
+   * Only periods a provider published, with the instant it published. A
+   * period before the first one this table can source is not guessed at: the
+   * earliest period stands for it, and the row's note says so.
+   */
+  history?: PricePeriod[];
   /**
    * Other ids that bill at exactly this rate.
    *

package/src/usage.ts

@@ -944,8 +944,20 @@ function add(into: UsageBreakdown, record: UsageRecord, catalogue: PricingCatalo
   if (!model) return false;
 
   countInto(into, record);
-  const { inputPerMTok, outputPerMTok } = effectivePricing(model, on);
-  const rates = multipliersFor(model);
+  /**
+   * **Each call at the price of its own moment.** A bill is history: a call
+   * made inside a promotion was billed at the promotional rate, a DeepSeek
+   * call at 03:00 UTC on a weekday was billed at peak, and a call before a
+   * published price change was billed at the old price. Priced at the report's
+   * date instead, every one of those came out at whatever applied the day the
+   * report ran: a clock-priced log read during peak hours was all peak, and an
+   * August log read in October lost its August promotion. `on` is the date for
+   * a record that carries no clock, which is the only thing it can mean here.
+   */
+  const at = record.ts !== null ? new Date(record.ts) : on;
+  const { inputPerMTok, outputPerMTok } = effectivePricing(model, at);
+  // Dated, like the rate above: a repriced cache read is part of the reprice.
+  const rates = multipliersFor(model, at);
   const per = (tokens: number, rate: number): number => (tokens / 1_000_000) * rate;
 
   into.inputUsd += per(record.inputTokens, inputPerMTok);
@@ -991,7 +1003,11 @@ function add(into: UsageBreakdown, record: UsageRecord, catalogue: PricingCatalo
 
 export interface UsageProfileOptions {
   catalogue: PricingCatalogue;
-  /** Date the prices are read at, so a promotional rate resolves the same way. */
+  /**
+   * The date a record with no timestamp is priced at, and the date the
+   * forward-looking findings (levers, what-ifs) are priced at. A record that
+   * carries its own `ts` is billed at its own moment: see `add`.
+   */
   on?: Date;
   /**
    * Profile only the records carrying this label — the drill-down, once the