tledger 0.3.1 → 0.4.0

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

@@ -0,0 +1,234 @@
+import {
+  API_USD_RATE_CARD_AS_OF,
+  CODEX_CREDIT_RATE_CARD,
+  CODEX_CREDIT_RATE_CARD_AS_OF,
+  apiUsdForUsage,
+  calculateCodexPurchasedCredits,
+  codexCreditMultiplier,
+  hasDetailedTokenBreakdown,
+  normalizeCodexCreditModel,
+} from "../lib/token-ledger-rates.mjs";
+import { sanitizeTerminalText } from "../lib/token-ledger-terminal-text.mjs";
+import {
+  snapshotFreshnessDetail,
+  sourceStatusLine,
+} from "./token-ledger-source-status.mjs";
+
+function nonNegative(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? Math.max(0, number) : 0;
+}
+
+function compact(value) {
+  const number = nonNegative(value);
+  if (number >= 1_000_000_000) return `${(number / 1_000_000_000).toFixed(1)}B`;
+  if (number >= 1_000_000) return `${(number / 1_000_000).toFixed(1)}M`;
+  if (number >= 1_000) return `${(number / 1_000).toFixed(1)}K`;
+  return Math.round(number).toLocaleString("en-US");
+}
+
+function percent(numerator, denominator) {
+  if (!(denominator > 0)) return "0.0%";
+  return `${((numerator / denominator) * 100).toFixed(1)}%`;
+}
+
+// Snapshot model identifiers are unbounded input; padding every row to an
+// unbounded column width would amplify one long label across the whole table.
+const MODEL_LABEL_MAX_WIDTH = 40;
+
+function modelLabel(model) {
+  const normalized = normalizeCodexCreditModel(model);
+  const labels = {
+    "gpt-6-astra": "GPT-6 Astra",
+    "gpt-5.6-sol": "GPT-5.6 Sol",
+    "gpt-5.6-terra": "GPT-5.6 Terra",
+    "gpt-5.6-luna": "GPT-5.6 Luna",
+    "gpt-5.5": "GPT-5.5",
+    "daybreak-blue": "Daybreak Blue",
+    "daybreak-red": "Daybreak Red",
+    "gpt-5.4": "GPT-5.4",
+    "gpt-5.4-mini": "GPT-5.4 mini",
+    "gpt-5.3-codex": "GPT-5.3 Codex",
+    "gpt-5.2": "GPT-5.2",
+  };
+  const label = sanitizeTerminalText(
+    normalized.includes("astra")
+      ? "GPT-6 Astra"
+      : labels[normalized] ?? String(model ?? "Unknown model"),
+  );
+  return label.length > MODEL_LABEL_MAX_WIDTH
+    ? `${label.slice(0, MODEL_LABEL_MAX_WIDTH - 1)}…`
+    : label;
+}
+
+function creditReason(event) {
+  const model = normalizeCodexCreditModel(
+    event?.rateCardModel ?? event?.model,
+  );
+  if (!CODEX_CREDIT_RATE_CARD[model]) return "unknown-model";
+  if (!hasDetailedTokenBreakdown(event)) return "incomplete-token-breakdown";
+  if (
+    codexCreditMultiplier(
+      event?.rateCardModel ?? event?.model,
+      event?.serviceTier,
+    ) === null
+  ) {
+    return "unsupported-credit-fast-tier";
+  }
+  return "unrated-credit-usage";
+}
+
+function eventEstimate(event, basis) {
+  if (basis === "api-usd") return apiUsdForUsage(event);
+  const amount = calculateCodexPurchasedCredits({
+    model: event?.rateCardModel ?? event?.model,
+    serviceTier: event?.serviceTier,
+    usage: event,
+  });
+  const totalTokens = nonNegative(event?.totalTokens);
+  if (amount === null) {
+    return {
+      amount: null,
+      ratedTokens: 0,
+      unratedTokens: totalTokens,
+      reasons: [creditReason(event)],
+    };
+  }
+  return {
+    amount,
+    ratedTokens: totalTokens,
+    unratedTokens: 0,
+    reasons: [],
+  };
+}
+
+function aggregate(events, basis) {
+  const models = new Map();
+  const reasons = new Map();
+  let amount = 0;
+  let amountKnown = false;
+  let ratedTokens = 0;
+  let unratedTokens = 0;
+
+  for (const event of events) {
+    const key = normalizeCodexCreditModel(event?.model);
+    const row = models.get(key) ?? {
+      model: modelLabel(event?.model),
+      inputTokens: 0,
+      cachedInputTokens: 0,
+      outputTokens: 0,
+      amount: 0,
+      amountKnown: false,
+      ratedTokens: 0,
+      unratedTokens: 0,
+    };
+    row.inputTokens += nonNegative(event?.inputTokens);
+    row.cachedInputTokens += Math.min(
+      nonNegative(event?.inputTokens),
+      nonNegative(event?.cachedInputTokens),
+    );
+    row.outputTokens += nonNegative(event?.outputTokens);
+    const estimate = eventEstimate(event, basis);
+    row.ratedTokens += estimate.ratedTokens;
+    row.unratedTokens += estimate.unratedTokens;
+    ratedTokens += estimate.ratedTokens;
+    unratedTokens += estimate.unratedTokens;
+    if (estimate.amount !== null) {
+      row.amount += estimate.amount;
+      row.amountKnown = true;
+      amount += estimate.amount;
+      amountKnown = true;
+    }
+    for (const reason of estimate.reasons) {
+      reasons.set(reason, (reasons.get(reason) ?? 0) + estimate.unratedTokens);
+    }
+    models.set(key, row);
+  }
+
+  return {
+    models: [...models.values()].sort((a, b) =>
+      b.ratedTokens + b.unratedTokens - (a.ratedTokens + a.unratedTokens)
+    ),
+    amount: amountKnown ? amount : null,
+    ratedTokens,
+    unratedTokens,
+    reasons,
+  };
+}
+
+function formatAmount(amount, basis) {
+  if (amount === null) return "—";
+  if (basis === "api-usd") {
+    return amount >= 0.01 ? `$${amount.toFixed(2)}` : `$${amount.toFixed(6)}`;
+  }
+  return `${amount.toFixed(3)} credits`;
+}
+
+function pad(value, width, align = "left") {
+  const text = String(value);
+  if (text.length >= width) return text;
+  const spaces = " ".repeat(width - text.length);
+  return align === "right" ? `${spaces}${text}` : `${text}${spaces}`;
+}
+
+export function renderCostTerminal({
+  events,
+  bounds,
+  basis,
+  snapshotFreshness = null,
+  sourceStatus = "unchecked-cache",
+}) {
+  const report = aggregate(events, basis);
+  const heading = basis === "api-usd"
+    ? "Hypothetical API-equivalent cost (USD)"
+    : "Codex purchased-credit estimate";
+  const amountLabel = basis === "api-usd" ? "USD" : "Credits";
+  const modelWidth = Math.max(
+    12,
+    ...report.models.map((row) => row.model.length),
+  );
+  const rows = report.models.map((row) => {
+    const rowTokens = row.ratedTokens + row.unratedTokens;
+    return [
+      pad(row.model, modelWidth),
+      pad(compact(row.inputTokens), 9, "right"),
+      pad(compact(row.cachedInputTokens), 9, "right"),
+      pad(compact(row.outputTokens), 9, "right"),
+      pad(formatAmount(row.amountKnown ? row.amount : null, basis), 16, "right"),
+      pad(percent(row.ratedTokens, rowTokens), 9, "right"),
+    ].join("  ");
+  });
+  const totalTokens = report.ratedTokens + report.unratedTokens;
+  const reasonLines = [...report.reasons.entries()]
+    .map(([reason, tokens]) => `${reason} (${compact(tokens)} tokens)`);
+  const cardDate = basis === "api-usd"
+    ? API_USD_RATE_CARD_AS_OF
+    : CODEX_CREDIT_RATE_CARD_AS_OF;
+  const footer = basis === "api-usd"
+    ? "Local history is incomplete account evidence; unsupported API charges are excluded. This is not an actual bill."
+    : "Purchased-credit rates do not infer included-plan or five-hour/weekly meter usage.";
+
+  return [
+    heading,
+    `Range: ${bounds.startDateString ?? bounds.start.toISOString()} through ${bounds.endDateString ?? bounds.end.toISOString()} (${bounds.timeZone})`,
+    `Snapshot: ${snapshotFreshnessDetail(snapshotFreshness)}`,
+    sourceStatusLine(sourceStatus),
+    "",
+    [
+      pad("Model", modelWidth),
+      pad("Input", 9, "right"),
+      pad("Cached", 9, "right"),
+      pad("Output", 9, "right"),
+      pad(amountLabel, 16, "right"),
+      pad("Coverage", 9, "right"),
+    ].join("  "),
+    ...rows,
+    "",
+    `Total rated amount: ${formatAmount(report.amount, basis)}`,
+    `Rated token coverage: ${percent(report.ratedTokens, totalTokens)}`,
+    `Unrated tokens: ${compact(report.unratedTokens)}`,
+    `Rate card as of: ${cardDate}`,
+    `Reasons: ${reasonLines.length > 0 ? reasonLines.join(", ") : "none"}`,
+    footer,
+  ].join("\n");
+}

package/bin/token-ledger-image-layout.mjs

@@ -0,0 +1,20 @@
+// Shared image-axis sizing rules. This module has no renderer or domain imports.
+
+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));
+}

package/bin/token-ledger-image-primitives.mjs

@@ -0,0 +1,192 @@
+// Shared, dependency-neutral values and SVG helpers used by image reports.
+
+export const TREND_IMAGE_MODEL_COLORS = {
+  Astra: "#e879f9",
+  Luna: "#3b82f6",
+  Sol: "#10a394",
+  Terra: "#8b7cf6",
+  "GPT-5.5": "#d55181",
+  "GPT-5.4": "#0891b2",
+  Daybreak: "#16a34a",
+  "Auto review": "#e5484d",
+  Other: "#64748b",
+  Unknown: "#64748b",
+  Unattributed: "#475569",
+};
+
+export const TREND_IMAGE_COLORS = {
+  background: "#0e1420",
+  panel: "#151d2c",
+  panelBorder: "#273246",
+  meterPanel: "#1b1712",
+  meterPanelBorder: "rgba(246,183,60,.4)",
+  ink: "#f2f5fa",
+  secondary: "#aeb8c9",
+  muted: "#77839a",
+  grid: "#1c2534",
+  baseline: "#33405a",
+  rule: "rgba(255,255,255,.1)",
+  track: "rgba(255,255,255,.09)",
+  projectTrack: "rgba(255,255,255,.07)",
+  line: "#f6b73c",
+  meterAxis: "#cf9a37",
+  chipFill: "#151d2c",
+  leftAxis: "#7ea2f0",
+  deltaUp: "#7fb37a",
+  deltaUpFill: "rgba(127,179,122,.14)",
+  deltaDown: "#e08a86",
+  deltaDownFill: "rgba(217,83,79,.16)",
+  remainderBar: "#475569",
+  onFill: "rgba(255,255,255,.82)",
+  cached: "#2ec4a1",
+  uncached: "#d88362",
+  weighted: "#c7d2e8",
+  cacheTrack: "#202a3a",
+};
+
+export const CACHE_IMAGE_COLORS = {
+  background: "#0e1420",
+  ink: "#f2f5fa",
+  secondary: "#aeb8c9",
+  muted: "#77839a",
+  grid: "#1c2534",
+  baseline: "#33405a",
+  track: "#202a3a",
+  cached: "#2ec4a1",
+  uncached: "#d88362",
+  volume: "#64748b",
+  weighted: "#c7d2e8",
+  rule: "rgba(255,255,255,.1)",
+};
+
+export const IMAGE_FONT_FAMILY = "system-ui, -apple-system, 'Segoe UI', sans-serif";
+export const IMAGE_MONO_FAMILY = "ui-monospace, Menlo, monospace";
+export const FAST_MODE_LABEL_COLOR = "#a78bfa";
+
+const XML_INVALID_CHARACTERS =
+  /[^\u0009\u000a\u000d\u0020-\uD7FF\uE000-\uFFFD\u{10000}-\u{10FFFF}]/gu;
+
+export function escapeXml(value) {
+  return String(value)
+    .replace(XML_INVALID_CHARACTERS, "")
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+export function compact(value, digits = 2) {
+  if (!Number.isFinite(value)) return "—";
+  const absolute = Math.abs(value);
+  const units = [
+    [1_000_000_000, "B"],
+    [1_000_000, "M"],
+    [1_000, "K"],
+  ];
+  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 : digits;
+    // 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, digits);
+    }
+    return `${scaled.toFixed(precision)}${suffix}`;
+  }
+  return Math.round(value).toLocaleString("en-US");
+}
+
+// Darker step of the same hue, used for the fast-mode share of a segment.
+export function fastShade(hexColor) {
+  const match = /^#([0-9a-f]{6})$/i.exec(String(hexColor));
+  if (!match) return hexColor;
+  const channels = [0, 2, 4].map((offset) =>
+    Math.round(parseInt(match[1].slice(offset, offset + 2), 16) * 0.62),
+  );
+  return `#${channels.map((value) => value.toString(16).padStart(2, "0")).join("")}`;
+}
+
+export function shiftCalendarDate(dateString, amount) {
+  const [year, month, day] = String(dateString).split("-").map(Number);
+  const date = new Date(Date.UTC(year, month - 1, day + amount));
+  return [date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate()]
+    .map((value, index) =>
+      index === 0 ? String(value) : String(value).padStart(2, "0"),
+    )
+    .join("-");
+}
+
+// Rough sans-serif advance widths in em units, for placing inline runs
+// (value + chip, legend items, pace rows). SVG has no flow layout.
+export function textWidth(text, size, weight = 400) {
+  let units = 0;
+  for (const character of String(text)) {
+    if (/[il.,:;'|!]/.test(character)) units += 0.3;
+    else if (/[Ijtfr\-()[\] ]/.test(character)) units += 0.37;
+    else if (/[mwMW@%]/.test(character)) units += 0.92;
+    else if (/[A-Z]/.test(character)) units += 0.7;
+    else if (/[0-9+±×−]/.test(character)) units += 0.58;
+    else units += 0.55;
+  }
+  return units * size * (weight >= 700 ? 1.05 : 1);
+}
+
+export function truncateText(text, maxWidth, size, weight = 400) {
+  let value = String(text ?? "").replace(/\.{3,}/g, "…");
+  if (!(maxWidth > 0) || textWidth(value, size, weight) <= maxWidth) return value;
+  if (value.includes("…")) {
+    const leading = `${value.split("…", 1)[0].trimEnd()}…`;
+    if (textWidth(leading, size, weight) <= maxWidth) return leading;
+    value = leading;
+  }
+  const ellipsis = "…";
+  const ellipsisWidth = textWidth(ellipsis, size, weight);
+  if (ellipsisWidth >= maxWidth) return ellipsis;
+
+  const characters = [...value];
+  let low = 0;
+  let high = characters.length;
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    const candidate = `${characters.slice(0, middle).join("")}${ellipsis}`;
+    if (textWidth(candidate, size, weight) <= maxWidth) low = middle;
+    else high = middle - 1;
+  }
+  return `${characters.slice(0, low).join("").trimEnd()}${ellipsis}`;
+}
+
+export function svgText({
+  x,
+  y,
+  value,
+  fill = TREND_IMAGE_COLORS.ink,
+  size = 12,
+  weight = 400,
+  anchor = "start",
+  spacing = null,
+  opacity = null,
+  mono = false,
+}) {
+  const spacingAttr = spacing ? ` letter-spacing="${spacing}"` : "";
+  const opacityAttr = opacity !== null ? ` opacity="${opacity}"` : "";
+  const family = mono ? IMAGE_MONO_FAMILY : IMAGE_FONT_FAMILY;
+  return `<text x="${x}" y="${y}" fill="${fill}" font-family="${family}" font-size="${size}px" font-weight="${weight}" text-anchor="${anchor}"${spacingAttr}${opacityAttr}>${escapeXml(value)}</text>`;
+}
+
+export function svgRect(x, y, width, height, attrs = {}) {
+  const pieces = [
+    `x="${Number(x).toFixed(2)}"`,
+    `y="${Number(y).toFixed(2)}"`,
+    `width="${Math.max(0, Number(width)).toFixed(2)}"`,
+    `height="${Math.max(0, Number(height)).toFixed(2)}"`,
+  ];
+  for (const [key, value] of Object.entries(attrs)) {
+    if (value === null || value === undefined) continue;
+    pieces.push(`${key}="${value}"`);
+  }
+  return `<rect ${pieces.join(" ")}/>`;
+}