tledger 0.2.1 → 0.3.1

package/bin/token-ledger-trend-terminal.mjs

@@ -1,4 +1,9 @@
 import { buildBurnDayBins, buildUsageTrend, trendModelLabel } from "./token-ledger-trend.mjs";
+import {
+  splitUsageBucketsAtBoundaries,
+  usageBuckets,
+  usageCallCount,
+} from "../lib/token-ledger-usage.mjs";
 
 const RESET = "\u001b[0m";
 const PRIMARY_STYLE = [38, 2, 255, 255, 255];
@@ -67,16 +72,23 @@ function fit(value, width, alignment = "left") {
 function compact(value) {
   if (!Number.isFinite(value)) return "—";
   const absolute = Math.abs(value);
-  for (const [divisor, suffix] of [
+  const units = [
     [1_000_000_000, "B"],
     [1_000_000, "M"],
     [1_000, "K"],
-  ]) {
-    if (absolute >= divisor) {
-      const scaled = value / divisor;
-      const precision = scaled >= 100 ? 0 : scaled >= 10 ? 1 : 2;
-      return `${scaled.toFixed(precision)}${suffix}`;
+  ];
+  for (let index = 0; index < units.length; index += 1) {
+    const [divisor, suffix] = units[index];
+    if (absolute < divisor) continue;
+    const scaled = value / divisor;
+    const magnitude = Math.abs(scaled);
+    const precision = magnitude >= 100 ? 0 : magnitude >= 10 ? 1 : 2;
+    // Values that round to 1000 of a unit belong to the next unit up
+    // (999,999 → 1.00M, not 1000K).
+    if (index > 0 && Number(magnitude.toFixed(precision)) >= 1_000) {
+      return compact(Math.sign(value) * divisor * 1_000);
     }
+    return `${scaled.toFixed(precision)}${suffix}`;
   }
   return Math.round(value).toLocaleString("en-US");
 }
@@ -122,8 +134,8 @@ function shiftCalendarDate(dateString, amount) {
   );
 }
 
-function timeZoneOffsetMs(instant, timeZone) {
-  const parts = new Intl.DateTimeFormat("en-US", {
+function timeZoneFormatter(timeZone) {
+  return new Intl.DateTimeFormat("en-US", {
     timeZone,
     timeZoneName: "longOffset",
     year: "numeric",
@@ -133,7 +145,11 @@ function timeZoneOffsetMs(instant, timeZone) {
     minute: "2-digit",
     second: "2-digit",
     hourCycle: "h23",
-  }).formatToParts(instant);
+  });
+}
+
+function timeZoneOffsetMs(instant, formatter) {
+  const parts = formatter.formatToParts(instant);
   const value = parts.find((part) => part.type === "timeZoneName")?.value ?? "GMT";
   if (value === "GMT") return 0;
   const match = value.match(/^GMT([+-])(\d{2}):?(\d{2})?$/);
@@ -142,20 +158,23 @@ function timeZoneOffsetMs(instant, timeZone) {
   return (match[1] === "+" ? 1 : -1) * minutes * 60 * 1_000;
 }
 
-function zonedMidnight(dateString, timeZone) {
+function zonedMidnight(
+  dateString,
+  timeZone,
+  formatter = timeZoneFormatter(timeZone),
+) {
   const [year, month, day] = dateParts(dateString);
   const utcGuess = Date.UTC(year, month - 1, day);
-  const first = new Date(utcGuess - timeZoneOffsetMs(new Date(utcGuess), timeZone));
-  return new Date(first.getTime() - timeZoneOffsetMs(first, timeZone));
+  const first = new Date(utcGuess - timeZoneOffsetMs(new Date(utcGuess), formatter));
+  return new Date(utcGuess - timeZoneOffsetMs(first, formatter));
 }
 
-function localDateString(timestamp, timeZone) {
-  const parts = new Intl.DateTimeFormat("en-US", {
-    timeZone,
-    year: "numeric",
-    month: "2-digit",
-    day: "2-digit",
-  }).formatToParts(new Date(timestamp));
+function localDateString(
+  timestamp,
+  timeZone,
+  formatter = timeZoneFormatter(timeZone),
+) {
+  const parts = formatter.formatToParts(new Date(timestamp));
   const values = Object.fromEntries(
     parts
       .filter((part) => part.type !== "literal")
@@ -175,9 +194,19 @@ function localDateLabel(dateString, timeZone) {
     .toUpperCase();
 }
 
-function chooseBinSize(days, width) {
-  if (days <= 14) return 1;
-  return width >= 120 ? 2 : 3;
+export function chooseBinSize(days, width, { minBinWidth = 1, preferDaily = false } = {}) {
+  const rangeDays = Number(days);
+  const plotWidth = Math.max(1, Number(width) || 1);
+  const minimumBinWidth = Math.max(1, Number(minBinWidth) || 1);
+  const maxBinCount = Math.max(1, Math.floor(plotWidth / minimumBinWidth));
+  const preferredBinSize = preferDaily
+    ? 1
+    : rangeDays <= 14
+      ? 1
+      : plotWidth >= 120
+        ? 2
+        : 3;
+  return Math.max(preferredBinSize, Math.ceil(rangeDays / maxBinCount));
 }
 
 function sortedModelEntries(values) {
@@ -186,8 +215,14 @@ function sortedModelEntries(values) {
     .sort(([left], [right]) => modelSort(left, right));
 }
 
-export function buildActualTokenBins(snapshot, bounds, days, width) {
-  const binSize = chooseBinSize(days, width);
+export function buildActualTokenBins(
+  snapshot,
+  bounds,
+  days,
+  width,
+  { binSize: forcedBinSize, minBinWidth, preferDaily } = {},
+) {
+  const binSize = forcedBinSize ?? chooseBinSize(days, width, { minBinWidth, preferDaily });
   const binCount = Math.ceil(days / binSize);
   const bins = Array.from({ length: binCount }, (_, index) => ({
     startDateString: shiftCalendarDate(bounds.startDateString, index * binSize),
@@ -207,18 +242,28 @@ export function buildActualTokenBins(snapshot, bounds, days, width) {
       index,
     ]),
   );
-
-  for (const event of snapshot.events ?? []) {
+  const dateFormatter = timeZoneFormatter(bounds.timeZone);
+  const binBoundaries = [
+    bins[0]?.startDateString,
+    ...bins.map((bin) => bin.endDateString),
+  ]
+    .filter(Boolean)
+    .map((dateString) =>
+      zonedMidnight(dateString, bounds.timeZone, dateFormatter).getTime());
+  for (const event of splitUsageBucketsAtBoundaries(
+    usageBuckets(snapshot),
+    binBoundaries,
+  )) {
     const timestamp = new Date(event.timestamp).getTime();
     if (!Number.isFinite(timestamp)) continue;
-    const dateString = localDateString(timestamp, bounds.timeZone);
+    const dateString = localDateString(timestamp, bounds.timeZone, dateFormatter);
     const dayIndex = dateIndexByString.get(dateString);
     if (dayIndex === undefined || dayIndex >= days) continue;
     const bin = bins[Math.floor(dayIndex / binSize)];
     const tokens = Math.max(0, Number(event.totalTokens) || 0);
     const model = trendModelLabel(event.model);
     bin.totalTokens += tokens;
-    bin.calls += 1;
+    bin.calls += usageCallCount(event);
     bin.values.set(model, (bin.values.get(model) ?? 0) + tokens);
     if (event.serviceTier === "priority") {
       bin.fastValues.set(model, (bin.fastValues.get(model) ?? 0) + tokens);

package/bin/token-ledger-trend.mjs

@@ -3,9 +3,15 @@ import {
   FAST_MODE_MULTIPLIER,
   RATE_CARD_AS_OF,
 } from "./token-ledger-rates.mjs";
+import {
+  splitUsageBucketsAtBoundaries,
+  usageBuckets,
+  usageBucketsInRange,
+} from "../lib/token-ledger-usage.mjs";
 
 const WEEK_MINUTES = 10_080;
 const RESET_JITTER_SECONDS = 5 * 60;
+const MAX_TREND_DAYS = 3_650;
 // Meter observations more than this far apart get their burn spread across
 // calendar days as an estimate rather than pinned to the observation day.
 const LONG_GAP_MS = 36 * 60 * 60 * 1_000;
@@ -92,8 +98,9 @@ function todayInTimeZone(timeZone) {
 }
 
 export function multiDayBounds(value, timeZone, rangeDays) {
-  if (![7, 14, 30].includes(Number(rangeDays))) {
-    throw new Error("Trend range must be 7, 14, or 30 days.");
+  const days = Number(rangeDays);
+  if (!Number.isSafeInteger(days) || days < 1 || days > MAX_TREND_DAYS) {
+    throw new Error(`Trend range must be between 1 and ${MAX_TREND_DAYS} days.`);
   }
   let endDateString = value;
   if (!endDateString || endDateString === "today") {
@@ -113,7 +120,7 @@ export function multiDayBounds(value, timeZone, rangeDays) {
   ) {
     throw new Error(`Invalid calendar day: ${endDateString}`);
   }
-  const startDateString = shiftCalendarDate(endDateString, -Number(rangeDays) + 1);
+  const startDateString = shiftCalendarDate(endDateString, -days + 1);
   return {
     dateString: endDateString,
     startDateString,
@@ -121,7 +128,7 @@ export function multiDayBounds(value, timeZone, rangeDays) {
     start: zonedMidnight(startDateString, timeZone),
     end: zonedMidnight(shiftCalendarDate(endDateString, 1), timeZone),
     timeZone,
-    rangeDays: Number(rangeDays),
+    rangeDays: days,
   };
 }
 
@@ -144,12 +151,20 @@ export function trendModelLabel(value) {
 
 export function weeklyQuotaObservations(snapshot = {}) {
   let observations = (snapshot.quotaObservations ?? [])
-    .map((observation) => ({
-      ...observation,
-      timestampMs: finiteTimestamp(observation.timestamp),
-      resetsAt: Number(observation.resetsAt),
-      usedPercent: Number(observation.usedPercent),
-    }))
+    .map((observation) => {
+      const timestampMs = finiteTimestamp(observation.timestamp);
+      const lastSeenAtMs = finiteTimestamp(observation.lastSeenAt);
+      return {
+        ...observation,
+        timestampMs,
+        observedThroughMs:
+          timestampMs === null
+            ? lastSeenAtMs
+            : Math.max(timestampMs, lastSeenAtMs ?? timestampMs),
+        resetsAt: Number(observation.resetsAt),
+        usedPercent: Number(observation.usedPercent),
+      };
+    })
     .filter(
       (observation) =>
         Number(observation.windowMinutes) === WEEK_MINUTES &&
@@ -270,6 +285,12 @@ export function normalizeQuotaTimeline(observations) {
           : Math.max(usedPercent, observation.usedPercent);
       normalized.push({
         ...observation,
+        observedThroughMs: Math.min(
+          Number.isFinite(observation.observedThroughMs)
+            ? observation.observedThroughMs
+            : observation.timestampMs,
+          nextFirstMs,
+        ),
         cycle,
         reset: !emitted && previousEpoch !== null,
         resetKind,
@@ -283,7 +304,7 @@ export function normalizeQuotaTimeline(observations) {
   return normalized;
 }
 
-function eventCredits(event) {
+export function eventCredits(event) {
   // Recompute from token components first so the current rate card applies;
   // snapshots can carry credits stored under an outdated card. Fast-mode
   // turns (service tier "priority") debit the limit at a higher rate.
@@ -416,10 +437,7 @@ function cloneAllocations(allocations) {
 function eventsInBounds(events, bounds) {
   const startMs = bounds.start.getTime();
   const endMs = bounds.end.getTime();
-  return events.filter((event) => {
-    const timestampMs = finiteTimestamp(event.timestamp);
-    return timestampMs !== null && timestampMs >= startMs && timestampMs < endMs;
-  });
+  return usageBucketsInRange({ events }, startMs, endMs);
 }
 
 function buildModelStats(displayedEvents, intervals, bounds) {
@@ -495,7 +513,7 @@ function buildModelStats(displayedEvents, intervals, bounds) {
 export function buildUsageTrend(snapshot = {}, bounds) {
   const startMs = bounds.start.getTime();
   const endMs = bounds.end.getTime();
-  const displayedEvents = eventsInBounds(snapshot.events ?? [], bounds);
+  const displayedEvents = eventsInBounds(usageBuckets(snapshot), bounds);
   const observations = normalizeQuotaTimeline(
     weeklyQuotaObservations(snapshot),
   ).filter((observation) => observation.timestampMs < endMs);
@@ -514,7 +532,17 @@ export function buildUsageTrend(snapshot = {}, bounds) {
     };
   }
 
-  const sortedEvents = (snapshot.events ?? [])
+  const sortedEvents = splitUsageBucketsAtBoundaries(
+    usageBuckets(snapshot),
+    [
+      startMs,
+      endMs,
+      ...observations.flatMap((observation) => [
+        observation.cycleStartMs,
+        observation.timestampMs,
+      ]),
+    ],
+  )
     .map((event) => ({ ...event, timestampMs: finiteTimestamp(event.timestamp) }))
     .filter((event) => event.timestampMs !== null && event.timestampMs < endMs)
     .sort((left, right) => left.timestampMs - right.timestampMs);
@@ -603,6 +631,7 @@ export function buildUsageTrend(snapshot = {}, bounds) {
     }
     points.push({
       timestampMs: observation.timestampMs,
+      observedThroughMs: observation.observedThroughMs,
       cycle: observation.cycle,
       usedPercent: observation.normalizedUsedPercent,
       remainingPercent: 100 - observation.normalizedUsedPercent,
@@ -631,15 +660,46 @@ export function buildUsageTrend(snapshot = {}, bounds) {
       (point) => point.timestampMs > startMs && point.timestampMs < endMs,
     ),
   );
-  const lastPoint = displayPoints.at(-1);
-  if (lastPoint) {
-    displayPoints.push({
-      ...lastPoint,
-      timestampMs: endMs,
-      observed: false,
-      carried: true,
-    });
+
+  // Repeated equal meter readings are compacted into an observed span. Extend
+  // each displayed cycle only through its last real sample; never synthesize a
+  // flat line through the unobserved remainder of the report range.
+  const sourcePointsByCycle = new Map();
+  for (const point of points) {
+    const cyclePoints = sourcePointsByCycle.get(point.cycle) ?? [];
+    cyclePoints.push(point);
+    sourcePointsByCycle.set(point.cycle, cyclePoints);
   }
+  const displayedCycles = new Set(displayPoints.map((point) => point.cycle));
+  for (const cycle of displayedCycles) {
+    const cyclePoints = sourcePointsByCycle.get(cycle) ?? [];
+    const displayedCyclePoints = displayPoints.filter(
+      (point) => point.cycle === cycle,
+    );
+    const lastPoint = displayedCyclePoints.at(-1);
+    if (!lastPoint || !cyclePoints.length) continue;
+    const observedThroughMs = Math.max(
+      ...cyclePoints.map((point) => point.observedThroughMs),
+    );
+    const nextResetMs = resets.find((reset) => reset.cycle === cycle + 1)
+      ?.timestampMs;
+    const crossesNextReset = Number.isFinite(nextResetMs) &&
+      observedThroughMs >= nextResetMs;
+    const endpointMs = Math.min(observedThroughMs, endMs);
+    if (!crossesNextReset && endpointMs > lastPoint.timestampMs) {
+      displayPoints.push({
+        ...lastPoint,
+        timestampMs: endpointMs,
+        observedThroughMs: endpointMs,
+        observed: true,
+        carried: false,
+        confirmation: true,
+      });
+    }
+  }
+  displayPoints.sort(
+    (left, right) => left.timestampMs - right.timestampMs || left.cycle - right.cycle,
+  );
 
   const hasUnattributed = methods.has("unattributed");
   let allocationMethod = "unavailable";
@@ -685,7 +745,7 @@ export function buildUsageTrend(snapshot = {}, bounds) {
     ).length,
     allocationMethod,
     observedThroughMs:
-      [...points].reverse().find((point) => point.timestampMs < endMs)
+      [...displayPoints].reverse().find((point) => point.observed)
         ?.timestampMs ?? null,
     rateCardAsOf: snapshot.provenance?.rateCardAsOf ?? RATE_CARD_AS_OF,
   };

package/bin/token-ledger-tui.mjs

@@ -22,7 +22,11 @@ export function startInteractive(view) {
   } = view;
   const stdin = process.stdin;
   const stdout = process.stdout;
-  if (!stdin.isTTY || !stdout.isTTY || typeof stdin.setRawMode !== "function") {
+  // Interactive mode needs a raw-mode-capable terminal on both ends. Capture
+  // the capability once here; the handlers below rely on it unconditionally.
+  const setRawMode =
+    stdin.isTTY && stdout.isTTY ? stdin.setRawMode?.bind(stdin) : null;
+  if (!setRawMode) {
     throw new Error("Interactive mode requires a terminal. Use --static when redirecting output.");
   }
 
@@ -53,7 +57,7 @@ export function startInteractive(view) {
       stdin.off("data", onData);
       stdout.off("resize", draw);
       process.off("SIGINT", onSignal);
-      if (stdin.isTTY) stdin.setRawMode(false);
+      setRawMode(false);
       stdin.pause();
       stdout.write(`${RESET}${SHOW_CURSOR}${EXIT_ALT_SCREEN}`);
       if (error) reject(error);
@@ -79,7 +83,7 @@ export function startInteractive(view) {
       }
     };
 
-    stdin.setRawMode(true);
+    setRawMode(true);
     stdin.setEncoding("utf8");
     stdin.resume();
     stdin.on("data", onData);