@trazum/cli 1.40.0 → 1.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.40.0",
+  "version": "1.41.0",
   "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",
@@ -37,7 +37,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@trazum/core": "1.40.0"
+    "@trazum/core": "1.41.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/connect.ts

@@ -0,0 +1,245 @@
+/**
+ * The fetch half of the connector: credentials, pagination, and what went
+ * missing.
+ *
+ * The transformation lives in `@trazum/core`, where it is testable without a
+ * network. This module does the part that touches the outside world, and it
+ * is written under three rules the rest of the product does not need:
+ *
+ * **A credential is borrowed, never held.** Keys are read from the environment
+ * at the moment of the call and never written to a config, a cache, a report
+ * or an error message. `redact` runs over everything that can reach a terminal
+ * — a key pasted into a CI log by an error handler is a key that has to be
+ * rotated, and the tool that leaked it is the tool that promised to save money.
+ *
+ * **The endpoint is not user-supplied.** Each provider has one fixed base URL
+ * compiled in. Trazum's SSRF story has been, since 1.14, that a request body
+ * must never *name* a host — it selects one. A usage connector that accepted
+ * `--base-url` would hand that property back for the convenience of a
+ * self-hosted proxy nobody has asked for yet.
+ *
+ * **A partial pull is a partial pull, out loud.** Rate limits, page caps and
+ * windows the provider has aged out all return what was gathered, with the
+ * gap named. A bill quietly short by an unknown amount is the failure this
+ * repository refuses everywhere it can occur, and a paginated API is exactly
+ * where it occurs.
+ */
+
+import { SAFE_FETCH_INIT } from '@trazum/core/node';
+import { normalizeAnthropicUsage, normalizeOpenAIUsage } from '@trazum/core';
+import type { ConnectorDescriptor, ConnectorPull, PullGap } from '@trazum/core';
+
+/** Fixed, compiled in, never taken from the caller. See the module note. */
+const ENDPOINTS: Record<string, string> = {
+  anthropic: 'https://api.anthropic.com/v1/organizations/usage_report/messages',
+  openai: 'https://api.openai.com/v1/organizations/usage/completions',
+};
+
+/**
+ * How many pages a single pull will walk before it stops and says so.
+ *
+ * A cap rather than an unbounded loop: a wrong window against a busy
+ * organisation is otherwise a request storm against somebody's rate limit,
+ * paid for by them. Reaching it is reported as a gap, never as a complete
+ * bill.
+ */
+const MAX_PAGES = 50;
+
+/** Requests in flight is always one: usage endpoints are strictly rate limited. */
+const REQUEST_TIMEOUT_MS = 30_000;
+
+export interface CredentialSource {
+  /** The environment variable the key came from — the *name*, never the value. */
+  variable: string;
+}
+
+/**
+ * Finds the credential without ever returning it to a caller that might print
+ * it: the key stays inside this module, and the caller gets the variable name.
+ */
+export function findCredential(
+  descriptor: ConnectorDescriptor,
+  env: Record<string, string | undefined>,
+): { key: string; source: CredentialSource } | null {
+  for (const variable of descriptor.credentialEnv) {
+    const value = env[variable];
+    if (typeof value === 'string' && value.trim() !== '') {
+      return { key: value.trim(), source: { variable } };
+    }
+  }
+  return null;
+}
+
+/**
+ * Removes credential material from anything on its way to a terminal.
+ *
+ * Two layers on purpose. The exact key is redacted because we hold it; the
+ * shapes are redacted because an error body may quote a *different* key —
+ * the one the caller mistyped, a key from a proxy's log line — and a leak
+ * through somebody else's error message is still a leak through Trazum's
+ * output.
+ */
+export function redact(text: string, key?: string): string {
+  let out = text;
+  if (key !== undefined && key.length >= 8) {
+    out = out.split(key).join('[redacted]');
+  }
+  return out
+    .replace(/sk-ant-[A-Za-z0-9_-]{8,}/g, '[redacted]')
+    .replace(/sk-[A-Za-z0-9_-]{16,}/g, '[redacted]')
+    .replace(/\bBearer\s+[A-Za-z0-9._-]{8,}/gi, 'Bearer [redacted]');
+}
+
+function headersFor(provider: string, key: string): Record<string, string> {
+  if (provider === 'anthropic') {
+    return { 'x-api-key': key, 'anthropic-version': '2023-06-01', accept: 'application/json' };
+  }
+  return { authorization: `Bearer ${key}`, accept: 'application/json' };
+}
+
+function urlFor(provider: string, fromMs: number, toMs: number, page: string | null): string {
+  const url = new URL(ENDPOINTS[provider]!);
+  if (provider === 'anthropic') {
+    url.searchParams.set('starting_at', new Date(fromMs).toISOString());
+    url.searchParams.set('ending_at', new Date(toMs).toISOString());
+    url.searchParams.set('bucket_width', '1d');
+    url.searchParams.append('group_by[]', 'model');
+  } else {
+    url.searchParams.set('start_time', String(Math.floor(fromMs / 1000)));
+    url.searchParams.set('end_time', String(Math.floor(toMs / 1000)));
+    url.searchParams.set('bucket_width', '1d');
+    url.searchParams.append('group_by[]', 'model');
+    url.searchParams.set('limit', '31');
+  }
+  if (page !== null) url.searchParams.set('page', page);
+  return url.toString();
+}
+
+export interface FetchUsageOptions {
+  descriptor: ConnectorDescriptor;
+  fromMs: number;
+  toMs: number;
+  env: Record<string, string | undefined>;
+  /** Injected so the whole path is testable without a network. */
+  fetchImpl?: typeof fetch;
+}
+
+export interface FetchUsageResult {
+  pull: ConnectorPull;
+  source: CredentialSource;
+  pages: number;
+}
+
+/**
+ * Pulls a window of usage, page by page, and reports what it could not get.
+ *
+ * Returns whatever was gathered when a page fails partway through: half a
+ * month with the gap named beats an exception that throws away the half that
+ * arrived, and beats a total that silently describes less traffic than the
+ * caller asked about.
+ */
+export async function fetchProviderUsage(options: FetchUsageOptions): Promise<FetchUsageResult> {
+  const { descriptor, fromMs, toMs, env, fetchImpl = fetch } = options;
+  const found = findCredential(descriptor, env);
+  if (found === null) {
+    throw new Error(
+      `No credential for ${descriptor.displayName}. Trazum reads it from the environment and never stores it — set ${descriptor.credentialEnv.join(' or ')} to ${descriptor.keyKind}. See ${descriptor.docs}.`,
+    );
+  }
+
+  const gaps: PullGap[] = [];
+  const payloads: unknown[] = [];
+  let page: string | null = null;
+  let pages = 0;
+
+  while (pages < MAX_PAGES) {
+    const url = urlFor(descriptor.id, fromMs, toMs, page);
+    let response: Response;
+    try {
+      response = await fetchImpl(url, {
+        ...SAFE_FETCH_INIT,
+        method: 'GET',
+        headers: headersFor(descriptor.id, found.key),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      gaps.push({
+        kind: 'rate-limited',
+        detail: `the request for page ${pages + 1} did not complete (${redact(message, found.key)}), so everything after it is missing from this window`,
+      });
+      break;
+    }
+    pages += 1;
+
+    if (response.status === 429) {
+      gaps.push({
+        kind: 'rate-limited',
+        detail: `the provider rate-limited page ${pages}, so this window stops early and the rest of it was not measured`,
+      });
+      break;
+    }
+    if (response.status === 401 || response.status === 403) {
+      throw new Error(
+        `${descriptor.displayName} refused the credential in ${found.source.variable} (HTTP ${response.status}). This endpoint needs ${descriptor.keyKind}; an ordinary API key cannot read the usage report.`,
+      );
+    }
+    if (!response.ok) {
+      const body = await response.text().catch(() => '');
+      throw new Error(
+        `${descriptor.displayName} returned HTTP ${response.status}: ${redact(body.slice(0, 400), found.key) || '(no body)'}`,
+      );
+    }
+
+    let payload: unknown;
+    try {
+      payload = await response.json();
+    } catch {
+      gaps.push({
+        kind: 'unreadable-entry',
+        detail: `page ${pages} was not readable JSON, so its buckets are missing from this window`,
+      });
+      break;
+    }
+    payloads.push(payload);
+
+    const more = (payload as { has_more?: unknown }).has_more === true;
+    const next = (payload as { next_page?: unknown }).next_page;
+    if (!more) break;
+    if (typeof next !== 'string' || next === '') {
+      gaps.push({
+        kind: 'cursor-expired',
+        detail: 'the provider said there was more and served no cursor to reach it, so this window is short by an unknown amount',
+      });
+      break;
+    }
+    page = next;
+  }
+
+  if (pages >= MAX_PAGES) {
+    gaps.push({
+      kind: 'page-limit',
+      detail: `the pull stopped at ${MAX_PAGES} pages, so this window is incomplete — narrow it with --since and --until`,
+    });
+  }
+
+  const normalize = descriptor.id === 'anthropic' ? normalizeAnthropicUsage : normalizeOpenAIUsage;
+  const pulls = payloads.map((payload) => normalize(payload));
+  const pull: ConnectorPull = {
+    provider: descriptor.id,
+    granularity: descriptor.granularity,
+    buckets: pulls.flatMap((p) => p.buckets),
+    window:
+      pulls.length === 0
+        ? null
+        : {
+            fromMs: Math.min(...pulls.filter((p) => p.window).map((p) => p.window!.fromMs), Infinity),
+            toMs: Math.max(...pulls.filter((p) => p.window).map((p) => p.window!.toMs), -Infinity),
+          },
+    gaps: [...pulls.flatMap((p) => p.gaps), ...gaps],
+    unavailable: descriptor.unavailable,
+  };
+  if (pull.window !== null && !Number.isFinite(pull.window.fromMs)) pull.window = null;
+
+  return { pull, source: found.source, pages };
+}

package/src/i18n/en.ts

@@ -42,6 +42,7 @@ ${bold('USAGE')}
   trazum plan <log.jsonl|dir> [options]
   trazum verify <plan.json> --against <newer.jsonl|dir> [options]
   trazum history <dir-of-stored-reports> [options]
+  trazum connect <anthropic|openai> [options]
   trazum diff <before> <after> [options]
   trazum diff --all <dir> <dir> [options]
   trazum rank <dir> [options]
@@ -319,6 +320,35 @@ ${bold('OPTIONS FOR plan')}
   a plan that hides its assumptions is advice pretending to be arithmetic.
   Projected savings and money already spent are separate totals throughout.
 
+${bold('OPTIONS FOR connect')}
+  --since <when>              The window to pull. A UTC day, an ISO timestamp,
+  --until <when>              a relative window (7d, 24h) or "now". Defaults to
+                              the last 30 days.
+  --dry-run                   Say what would be called and which environment
+                              variable the key would come from. Sends nothing
+                              and needs no credential.
+  --payload <file>            Price a usage payload you already have, instead of
+                              pulling one. No credential, no network — the same
+                              arithmetic on the same shape.
+  -o, --out <file>            Save the priced report as JSON.
+  --markdown-out <file>       Also write it as Markdown, for a CI job summary.
+  --json                      The report as data.
+
+  Reads your bill from the provider's usage API, so nothing has to be exported
+  by hand. The credential is read from the environment at the moment of the
+  call and never stored, never printed and never written to a config: set
+  TRAZUM_ANTHROPIC_ADMIN_KEY or TRAZUM_OPENAI_ADMIN_KEY. Each provider needs
+  the narrowest key that can read a usage report, and an ordinary API key
+  cannot.
+
+  These APIs serve sums over a window, not one row per call, so a connected
+  report is a restricted one and says so: the totals, the model split, the day
+  series and the cache verdict are all available, and the per-call findings —
+  input shapes, truncation retries, conversations, context pressure — are
+  listed as unavailable with what would unlock them. A rate limit, a page cap
+  or an expired cursor returns what arrived with the gap named, never a total
+  that quietly describes less traffic than you asked about.
+
 ${bold('OPTIONS FOR history')}
   --markdown-out <file>       Also write the series as Markdown, for a CI job
                               summary or a pull request comment.
@@ -1447,6 +1477,37 @@ ${bold('EXAMPLES')}
       `Plan written to ${path}, dated. Keep it: a prediction nobody wrote down is a prediction nobody can be held to.`,
   },
 
+  connect: {
+    noTarget: (providers) =>
+      `Name a provider to read your bill from: trazum connect anthropic. Available: ${providers}. The credential comes from the environment and is never stored — add --dry-run to see exactly what would be called and which variable it would be read from.`,
+    unknownProvider: (id, providers) =>
+      `There is no connector for "${id}". The ones that exist are: ${providers}.`,
+    dryRun: (provider, from, to, envVars, keyKind) =>
+      `Would read ${provider} usage from ${from} to ${to}, using ${keyKind} taken from ${envVars}. Nothing was sent and no credential was needed to print this.`,
+    heading: (provider, from, to, usd, calls) =>
+      calls === null
+        ? `${provider} · ${from} → ${to} · ${usd}`
+        : `${provider} · ${from} → ${to} · ${usd} · ${calls} calls`,
+    modelRow: (model, usd, share, calls) =>
+      calls === null ? `${model}  ${usd}  ${share}` : `${model}  ${usd}  ${share} · ${calls} calls`,
+    nothingBilled: () =>
+      'The provider billed nothing in this window. That is a measurement, not an error — widen it with --since if you expected traffic.',
+    cachePaid: (saved) => `Caching paid for itself: ${saved} less than these tokens would have cost as ordinary input.`,
+    cacheLost: (added) => `Caching added ${added} to this bill against what the same tokens would have cost as ordinary input.`,
+    cacheUnsettled: () =>
+      'This source did not say which TTL the cache writes used, so the cheaper rate was assumed and the verdict moves under the other one. Unsettled, not settled in your favour.',
+    noCallCount: (provider) =>
+      `${provider}'s usage report serves token sums and no request count, so there is no call count here and no per-call average. A zero would read as "no traffic", so nothing is printed instead.`,
+    unpriced: (model, tokens) =>
+      `${model} is not in the price catalogue, so its ${tokens} tokens are counted and its money is not. Add it with --pricing rather than reading the total as complete.`,
+    gap: (detail) => `This window is incomplete: ${detail}.`,
+    unavailable: (findings) =>
+      `Findings this source cannot support: ${findings}. They need one row per call, and a sum has lost the rows — a per-call log still answers them.`,
+    wrote: (path) => `Report written to ${path}.`,
+    footer: () =>
+      'Every figure here is the provider\u2019s own billed token count at the catalogue\u2019s rates. Nothing was estimated, and nothing the provider did not serve was filled in.',
+  },
+
   history: {
     noTarget: () =>
       'Point this at a directory of stored reports: trazum history reports/. It reads the --json documents "trazum profile" writes (and any saved plans beside them) and builds the series no pairwise comparison can see.',

package/src/i18n/es.ts

@@ -29,6 +29,7 @@ ${bold('USO')}
   trazum plan <log.jsonl|dir> [opciones]
   trazum verify <plan.json> --against <nuevo.jsonl|dir> [opciones]
   trazum history <dir-de-informes-guardados> [opciones]
+  trazum connect <anthropic|openai> [opciones]
   trazum diff <antes> <después> [opciones]
   trazum diff --all <dir> <dir> [opciones]
   trazum rank <dir> [opciones]
@@ -326,6 +327,36 @@ ${bold('OPCIONES DE plan')}
   consejo haciéndose pasar por aritmética. El ahorro proyectado y el dinero ya
   gastado son totales separados en todas partes.
 
+${bold('OPCIONES DE connect')}
+  --since <cuándo>            La ventana que se descarga. Un día UTC, una marca
+  --until <cuándo>            ISO, una ventana relativa (7d, 24h) o "now". Por
+                              defecto, los últimos 30 días.
+  --dry-run                   Dice qué se llamaría y de qué variable de entorno
+                              saldría la clave. No envía nada y no necesita
+                              credencial.
+  --payload <fichero>         Tasa un payload de uso que ya tengas, en vez de
+                              descargar uno. Sin credencial y sin red — la misma
+                              aritmética sobre la misma forma.
+  -o, --out <fichero>         Guarda el informe tasado como JSON.
+  --markdown-out <fichero>    Lo escribe además como Markdown, para CI.
+  --json                      El informe como datos.
+
+  Lee tu factura desde la API de uso del proveedor, para que nadie tenga que
+  exportar nada a mano. La credencial se lee del entorno en el momento de la
+  llamada y nunca se guarda, nunca se imprime y nunca se escribe en un fichero
+  de configuración: define TRAZUM_ANTHROPIC_ADMIN_KEY o TRAZUM_OPENAI_ADMIN_KEY.
+  Cada proveedor necesita la clave más estrecha que pueda leer un informe de
+  uso, y una clave de API normal no puede.
+
+  Estas APIs sirven sumas sobre una ventana, no una fila por llamada, así que
+  un informe conectado es un informe restringido y lo dice: los totales, el
+  reparto por modelo, la serie por día y el veredicto de caché están todos
+  disponibles, y los hallazgos por llamada — formas de entrada, reintentos por
+  truncado, conversaciones, presión de contexto — se listan como no disponibles
+  con lo que los desbloquearía. Un límite de tasa, un tope de páginas o un
+  cursor caducado devuelven lo que llegó con el hueco nombrado, nunca un total
+  que describe en silencio menos tráfico del que pediste.
+
 ${bold('OPCIONES DE history')}
   --markdown-out <fichero>    Escribe además la serie como Markdown, para un
                               resumen de CI o un comentario de pull request.
@@ -1470,6 +1501,37 @@ ${bold('EJEMPLOS')}
       `Plan escrito en ${path}, con fecha. Guárdalo: una predicción que nadie apuntó es una predicción que no se le puede exigir a nadie.`,
   },
 
+  connect: {
+    noTarget: (providers) =>
+      `Nombra un proveedor del que leer tu factura: trazum connect anthropic. Disponibles: ${providers}. La credencial sale del entorno y nunca se guarda — añade --dry-run para ver exactamente qué se llamaría y de qué variable saldría.`,
+    unknownProvider: (id, providers) =>
+      `No hay conector para "${id}". Los que existen son: ${providers}.`,
+    dryRun: (provider, from, to, envVars, keyKind) =>
+      `Leería el uso de ${provider} del ${from} al ${to}, usando ${keyKind} tomada de ${envVars}. No se envió nada y no hizo falta ninguna credencial para imprimir esto.`,
+    heading: (provider, from, to, usd, calls) =>
+      calls === null
+        ? `${provider} · ${from} → ${to} · ${usd}`
+        : `${provider} · ${from} → ${to} · ${usd} · ${calls} llamadas`,
+    modelRow: (model, usd, share, calls) =>
+      calls === null ? `${model}  ${usd}  ${share}` : `${model}  ${usd}  ${share} · ${calls} llamadas`,
+    nothingBilled: () =>
+      'El proveedor no facturó nada en esta ventana. Eso es una medición, no un error — ensánchala con --since si esperabas tráfico.',
+    cachePaid: (saved) => `La caché se pagó sola: ${saved} menos de lo que estos tokens habrían costado como entrada normal.`,
+    cacheLost: (added) => `La caché añadió ${added} a esta factura frente a lo que los mismos tokens habrían costado como entrada normal.`,
+    cacheUnsettled: () =>
+      'Esta fuente no dijo con qué TTL se escribió la caché, así que se asumió la tarifa barata y el veredicto cambia con la otra. Sin resolver, no resuelto a tu favor.',
+    noCallCount: (provider) =>
+      `El informe de uso de ${provider} sirve sumas de tokens y ningún recuento de peticiones, así que aquí no hay número de llamadas ni media por llamada. Un cero se leería como "sin tráfico", así que no se imprime nada en su lugar.`,
+    unpriced: (model, tokens) =>
+      `${model} no está en el catálogo de precios, así que sus ${tokens} tokens se cuentan y su dinero no. Añádelo con --pricing en vez de leer el total como completo.`,
+    gap: (detail) => `Esta ventana está incompleta: ${detail}.`,
+    unavailable: (findings) =>
+      `Hallazgos que esta fuente no puede sostener: ${findings}. Necesitan una fila por llamada, y una suma ha perdido las filas — un registro por llamada sí los responde.`,
+    wrote: (path) => `Informe escrito en ${path}.`,
+    footer: () =>
+      'Cada cifra de aquí es el recuento de tokens que el proveedor facturó, a las tarifas del catálogo. No se estimó nada, y no se rellenó nada que el proveedor no sirviera.',
+  },
+
   history: {
     noTarget: () =>
       'Apunta esto a un directorio de informes guardados: trazum history informes/. Lee los documentos --json que escribe "trazum profile" (y los planes guardados que haya al lado) y construye la serie que ninguna comparación por pares puede ver.',

package/src/i18n/types.ts

@@ -1072,6 +1072,38 @@ export interface CliMessages {
     wrote(path: string): string;
   };
 
+  /**
+   * `trazum connect` — the bill, read from the provider.
+   *
+   * A usage API serves sums, so the report is restricted on purpose and says
+   * which findings this source cannot support. The credential copy matters as
+   * much as the figures: Trazum borrows a key from the environment and never
+   * stores it, and the messages here are where a user learns that.
+   */
+  connect: {
+    noTarget(providers: string): string;
+    unknownProvider(id: string, providers: string): string;
+    /** What would be called, with no key needed and nothing sent. */
+    dryRun(provider: string, from: string, to: string, envVars: string, keyKind: string): string;
+    /** `calls` is null on a source that serves no request count. */
+    heading(provider: string, from: string, to: string, usd: string, calls: string | null): string;
+    modelRow(model: string, usd: string, share: string, calls: string | null): string;
+    /** A window the provider billed nothing in — not an error, and not a zero to hide. */
+    nothingBilled(): string;
+    cachePaid(saved: string): string;
+    cacheLost(added: string): string;
+    /** The write TTL was not stated, so the verdict moves under the other rate. */
+    cacheUnsettled(): string;
+    /** This source serves token sums and no request count. */
+    noCallCount(provider: string): string;
+    unpriced(model: string, tokens: string): string;
+    /** Something the pull did not get, named rather than silently missing. */
+    gap(detail: string): string;
+    unavailable(findings: string): string;
+    wrote(path: string): string;
+    footer(): string;
+  };
+
   /**
    * `trazum history` — many reports over many periods, as one series.
    *