@letterstory/cli 0.73.1 → 0.75.0

package/lib/cli.mjs

@@ -56,7 +56,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.73.1";
+export const VERSION = "0.75.0";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -581,6 +581,19 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        session (a trial per arm), linked to its
                                                        ledger entry. Written by \`npm run lab --
                                                        publish\` in the kernels repo.
+  admin spend summary [--range day|week|month|year | --from D --to D] [--grain day|week|month]
+          | entries [--from D] [--to D] [--vendor V] [--area A] [--source invoice|csv_import|api|manual]
+          | add --vendor V --amount N --from D [--to D] --area A --category C [--basis billed|estimated] …
+          | import <file.csv> [--vendor Concentrate] [--area A] [--keep-ledger-key] [--dry-run]
+          | usage <events.json>                       per-call costs as kernels/lettertrace push them
+          | remove <entry-id> | services | service <slug> [--owner …] [--monthly N|none] [--renewal D]
+                                                       Where Letter's money goes (spending.letter.dev):
+                                                       totals, run rate, area/vendor/provider/model/
+                                                       key/operation/org breakdowns, every number's
+                                                       source and basis, and the data gaps. Entries
+                                                       cover what the app ledger cannot see; a CSV
+                                                       import sums Concentrate's log export.
+                                                       Needs spend:read (reads) / spend:write (writes).
   admin crm import <file.csv> [--source <name>] [--tag "…"] [--dry-run]
           | capture [shot.png …] [--text "…" | --text-file f] [--context "this is for acme.com"]
                     [--account <id>] [--dry-run]   screenshots / a thread / a note → a lead

package/lib/commands/admin.mjs

@@ -13,6 +13,7 @@
 //      The old names — evals, eval-add, eval-set, proposals, propose-eval, capture-eval, reject-eval — still work.)
 //   admin evals scoreboard|cases|runs|run|triage|guard|retire …                      (fleet:read / tuning:experiment)
 //   admin crm import|capture|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|record-churn|undo-churn|onboard|onboarding|retry-onboarding|onboard-plan|payment-link …  (crm:read / crm:write)
+//   admin spend summary|entries|add|import|usage|remove|services|service …                (spend:read / spend:write)
 //   admin replays [--org <id>] [--target <id>] [--status …] [--limit n]                (fleet:read)
 //   admin replay --org <id> [<response-id> | --target <id>] [--surface …]           (fleet:replay)
 //   admin create-org --domain acme.com [--name "Acme"] [--test] [--no-key] [--key-name N]
@@ -2998,11 +2999,258 @@ async function cmdAdminReplays(ctx, sub) {
 	return 0;
 }
 
+// ─── admin spend ─────────────────────────────────────────────────────────────
+// The headless half of spending.letter.dev: the same getSpendSummary, entries and services
+// the dashboard reads, through /api/superadmin/spend/*, so a background agent can watch
+// spend 24/7. Reads need spend:read on the staff key, writes spend:write.
+
+const SPEND = "/api/superadmin/spend";
+const SPEND_RANGES = ["day", "week", "month", "year"];
+const SPEND_GRAINS = ["day", "week", "month"];
+const SPEND_CATEGORIES = [
+	"ai_model",
+	"ai_media",
+	"search_scrape",
+	"data_enrichment",
+	"email_sms",
+	"infra",
+	"analytics",
+	"payments",
+	"devtools",
+	"other",
+];
+const SPEND_BASES = ["billed", "estimated"];
+const SPEND_SOURCES = ["invoice", "csv_import", "api", "manual"];
+
+function usd(n) {
+	return `$${Number(n ?? 0).toLocaleString("en-US", { maximumFractionDigits: n >= 100 ? 0 : 2 })}`;
+}
+
+function formatSpendSummary(s) {
+	const t = s.totals;
+	const lines = [
+		`${s.range.from} → ${s.range.to} (${s.range.days}d): ${usd(t.total)}  ·  ${usd(t.perDay)}/day  ·  ~${usd(t.projectedMonth)}/mo` +
+			(t.changePct === null ? "" : `  ·  ${t.changePct > 0 ? "+" : ""}${t.changePct}% vs previous`),
+		`  billed ${usd(t.billed)}  ·  reported ${usd(t.reported)}  ·  estimated (list price) ${usd(t.estimated)}`,
+		"",
+		"By area:",
+		...s.areas.map((a) => `  ${a.label.padEnd(34)} ${usd(a.total).padStart(10)}`),
+		"",
+		"Top operations (letterstory):",
+		...s.drill.slice(0, 8).map((d) => `  ${d.operation.padEnd(34)} ${usd(d.total).padStart(10)}  ${d.calls} calls`),
+		"",
+		"Top orgs:",
+		...s.orgs
+			.slice(0, 10)
+			.map(
+				(o) =>
+					`  ${o.name.slice(0, 34).padEnd(34)} ${usd(o.total).padStart(10)}${o.internal ? `  [${o.internalReason}]` : ""}${o.paying === false && !o.internal ? "  [not paying]" : ""}`
+			),
+	];
+	if (s.gaps.length) lines.push("", "Not in the total:", ...s.gaps.map((g) => `  ${g.label}: ${g.reason}`));
+	return lines.join("\n");
+}
+
+function formatSpendServices(r) {
+	return (r.services ?? [])
+		.map(
+			(x) =>
+				`${x.slug.padEnd(22)} ${x.category.padEnd(16)} ${x.live === true ? "live" : x.live === false ? "off " : "  ? "}  ${x.hasCostData ? usd(x.spend30d).padStart(9) + "/30d" : "  no cost data"}${x.owner ? `  owner ${x.owner}` : ""}`
+		)
+		.join("\n");
+}
+
+function spendEntryFromFlags(flags) {
+	const vendor = flagStr(flags.vendor);
+	const amount = flagNum(flags.amount);
+	const start = flagStr(flags.from) ?? flagStr(flags.day);
+	const end = flagStr(flags.to) ?? start;
+	if (!vendor || amount === undefined || !start) {
+		throw new CliError(
+			'Usage: admin spend add --vendor Perplexity --amount 412.50 --from 2026-09-01 [--to 2026-09-30] --area lettertrace --category ai_model [--basis billed|estimated] [--source invoice|manual] [--key "…"] [--model …] [--operation …] [--service <slug>] [--ref "invoice #123"] [--note "…"] [--external-id …]'
+		);
+	}
+	return compact({
+		vendor,
+		amount_usd: amount,
+		period_start: start,
+		period_end: end,
+		area: flagStr(flags.area) ?? "other",
+		category: oneOf(flags, "category", SPEND_CATEGORIES) ?? "other",
+		basis: oneOf(flags, "basis", SPEND_BASES) ?? "billed",
+		source: oneOf(flags, "source", SPEND_SOURCES) ?? "manual",
+		key_label: flagStr(flags.key),
+		model: flagStr(flags.model),
+		operation: flagStr(flags.operation),
+		service_slug: flagStr(flags.service),
+		provider: flagStr(flags.provider),
+		org_id: flagStr(flags.org),
+		source_ref: flagStr(flags.ref),
+		note: flagStr(flags.note),
+		external_id: flagStr(flags["external-id"]),
+	});
+}
+
+async function cmdAdminSpend(ctx) {
+	const { flags, positionals, io } = ctx;
+	const sub = positionals[0];
+	switch (sub) {
+		case "summary": {
+			const params = new URLSearchParams(
+				compact({
+					range: oneOf(flags, "range", SPEND_RANGES),
+					from: flagStr(flags.from),
+					to: flagStr(flags.to),
+					grain: oneOf(flags, "grain", SPEND_GRAINS),
+				})
+			);
+			const result = await staffRequest(ctx, "GET", `${SPEND}/summary${params.size ? `?${params}` : ""}`);
+			printResult(io, flags, result, formatSpendSummary);
+			return 0;
+		}
+		case "entries": {
+			const params = new URLSearchParams(
+				compact({
+					from: flagStr(flags.from),
+					to: flagStr(flags.to),
+					vendor: flagStr(flags.vendor),
+					area: flagStr(flags.area),
+					source: oneOf(flags, "source", SPEND_SOURCES),
+					limit: flagNum(flags.limit)?.toString(),
+				})
+			);
+			const result = await staffRequest(ctx, "GET", `${SPEND}/entries${params.size ? `?${params}` : ""}`);
+			printResult(io, flags, result, (r) =>
+				(r.entries ?? [])
+					.map(
+						(e) =>
+							`${e.period_start}→${e.period_end}  ${usd(e.amount_usd).padStart(10)}  ${e.vendor}${e.key_label ? `: ${e.key_label}` : ""}  [${e.area}, ${e.basis}, ${e.source}]  ${e.id}`
+					)
+					.join("\n")
+			);
+			return 0;
+		}
+		case "add": {
+			const result = await staffPost(ctx, `${SPEND}/entries`, spendEntryFromFlags(flags));
+			ok(ctx, `Recorded ${result.created} new, ${result.replaced} replaced.`);
+			printResult(io, flags, result);
+			return 0;
+		}
+		case "import": {
+			const path = positionals[1];
+			if (!path)
+				throw new CliError(
+					'Usage: admin spend import <file.csv> [--vendor Concentrate] [--area kernels] [--category ai_model] [--basis billed|estimated] [--ref "…"] [--keep-ledger-key] [--dry-run]'
+				);
+			const body = compact({
+				csv: readFileSync(path, "utf8"),
+				vendor: flagStr(flags.vendor),
+				area: flagStr(flags.area),
+				category: oneOf(flags, "category", SPEND_CATEGORIES),
+				basis: oneOf(flags, "basis", SPEND_BASES),
+				source_ref: flagStr(flags.ref) ?? `CSV import: ${path.split("/").pop()}`,
+				exclude_ledger_key: flagBool(flags["keep-ledger-key"]) ? null : undefined,
+				dry_run: flagBool(flags["dry-run"]) || undefined,
+			});
+			const result = await staffPost(ctx, `${SPEND}/import`, body);
+			ok(
+				ctx,
+				`${result.used} of ${result.rows} rows → ${result.entries.length} entries, ${usd(result.total)}` +
+					(result.days ? ` (${result.days.from} → ${result.days.to})` : "") +
+					(result.excludedLedgerRows
+						? `; ${result.excludedLedgerRows} BYOK rows on the ledger's key dropped`
+						: "") +
+					(flagBool(flags["dry-run"]) ? " (dry run, nothing written)" : "")
+			);
+			if (result.overlaps?.length) {
+				ok(
+					ctx,
+					`Already on file for those days (may now double count): ${result.overlaps.map((o) => `${o.vendor} ${o.key_label ?? ""} ${o.id}`).join("; ")}`
+				);
+			}
+			printResult(io, flags, result, () => "");
+			return 0;
+		}
+		case "usage": {
+			// Per-call model costs, as kernels / lettertrace push them (POST /api/superadmin/spend/usage):
+			// a JSON file holding { events: [...] } or a bare array. Idempotent on each event_id.
+			const path = positionals[1];
+			if (!path) throw new CliError("Usage: admin spend usage <events.json>   ({ events: [...] } or an array)");
+			const parsed = JSON.parse(readFileSync(path, "utf8"));
+			const events = Array.isArray(parsed) ? parsed : parsed?.events;
+			if (!Array.isArray(events) || events.length === 0) throw new CliError(`${path} holds no events.`);
+			let inserted = 0;
+			let duplicates = 0;
+			let cost = 0;
+			const rejected = [];
+			for (let i = 0; i < events.length; i += 1000) {
+				const r = await staffPost(ctx, `${SPEND}/usage`, { events: events.slice(i, i + 1000) });
+				inserted += r.inserted;
+				duplicates += r.duplicates;
+				cost += r.cost_usd;
+				rejected.push(...(r.rejected ?? []));
+			}
+			ok(
+				ctx,
+				`${events.length} events: ${inserted} new (${usd(cost)}), ${duplicates} already on file` +
+					(rejected.length ? `, ${rejected.length} refused` : "")
+			);
+			printResult(
+				io,
+				flags,
+				{ received: events.length, inserted, duplicates, cost_usd: cost, rejected },
+				() => ""
+			);
+			return 0;
+		}
+		case "remove": {
+			const id = positionals[1];
+			if (!id) throw new CliError("Usage: admin spend remove <entry-id>");
+			const result = await staffRequest(ctx, "DELETE", `${SPEND}/entries/${encodeURIComponent(id)}`);
+			ok(ctx, `Removed ${id}.`);
+			printResult(io, flags, result);
+			return 0;
+		}
+		case "services": {
+			const result = await staffRequest(ctx, "GET", `${SPEND}/services`);
+			printResult(io, flags, result, formatSpendServices);
+			return 0;
+		}
+		case "service": {
+			const slug = positionals[1];
+			const monthly = flags.monthly === "none" ? null : flagNum(flags.monthly);
+			const update = compact({
+				owner: flagStr(flags.owner),
+				plan: flagStr(flags.plan),
+				monthly_cost_usd: monthly,
+				renewal_date: flagStr(flags.renewal),
+				notes: flagStr(flags.notes),
+				billing_source: oneOf(flags, "billing", ["api", "invoice", "unknown"]),
+			});
+			if (flags.monthly === "none") update.monthly_cost_usd = null;
+			if (!slug || Object.keys(update).length === 0) {
+				throw new CliError(
+					'Usage: admin spend service <slug> [--owner "Steve"] [--plan "Pro"] [--monthly 20|none] [--renewal 2026-11-01] [--notes "…"] [--billing api|invoice|unknown]'
+				);
+			}
+			const result = await staffRequest(ctx, "PATCH", `${SPEND}/services/${encodeURIComponent(slug)}`, update);
+			ok(ctx, `Updated ${slug}.`);
+			printResult(io, flags, result);
+			return 0;
+		}
+		default:
+			throw new CliError(
+				"Usage: admin spend summary [--range day|week|month|year | --from D --to D] [--grain day|week|month] | entries [--from D] [--to D] [--vendor V] [--area A] [--source S] | add --vendor V --amount N --from D … | import <file.csv> … | usage <events.json> | remove <entry-id> | services | service <slug> --owner … --monthly …"
+			);
+	}
+}
+
 export async function cmdAdmin(ctx) {
 	const sub = ctx.positionals[0];
 	if (sub === "replays" || sub === "replay")
 		return cmdAdminReplays({ ...ctx, positionals: ctx.positionals.slice(1) }, sub);
 	if (sub === "crm") return cmdAdminCrm({ ...ctx, positionals: ctx.positionals.slice(1) });
+	if (sub === "spend") return cmdAdminSpend({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "create-org") return cmdAdminCreateOrg({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "ask") return cmdAdminAsk({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "experiments") return cmdAdminExperiments({ ...ctx, positionals: ctx.positionals.slice(1) });
@@ -3011,6 +3259,6 @@ export async function cmdAdmin(ctx) {
 	if (sub === "tuning") return cmdAdminTuning({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "evals") return cmdAdminEvals({ ...ctx, positionals: ctx.positionals.slice(1) });
 	throw new CliError(
-		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin experiments … | admin crm … | admin evals … | admin tuning … | admin tuning-context | admin replays … (see --help)'
+		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin experiments … | admin crm … | admin spend … | admin evals … | admin tuning … | admin tuning-context | admin replays … (see --help)'
 	);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@letterstory/cli",
-	"version": "0.73.1",
+	"version": "0.75.0",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",