@letterstory/cli 0.74.0 → 0.76.0

package/lib/cli.mjs

@@ -56,7 +56,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.74.0";
+export const VERSION = "0.76.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.
@@ -582,9 +582,14 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        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]
+          | reconcile [--from D --to D] | pnl [--range day|week|month|year | --from D --to D]
+          | reference add --vendor V [--key K] --metric billed_usd --value N --from D [--to D] --ref "…"
+          | stripe-sync --from D --to D
           | 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] [--ledger-key K] [--dry-run]
           | 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/

package/lib/commands/admin.mjs

@@ -13,7 +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|remove|services|service …                (spend:read / spend:write)
+//   admin spend summary|reconcile|pnl|entries|add|import|usage|remove|reference|stripe-sync|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]
@@ -3019,7 +3019,7 @@ const SPEND_CATEGORIES = [
 	"devtools",
 	"other",
 ];
-const SPEND_BASES = ["billed", "estimated"];
+const SPEND_BASES = ["billed", "reported", "estimated"];
 const SPEND_SOURCES = ["invoice", "csv_import", "api", "manual"];
 
 function usd(n) {
@@ -3088,6 +3088,8 @@ function spendEntryFromFlags(flags) {
 		source_ref: flagStr(flags.ref),
 		note: flagStr(flags.note),
 		external_id: flagStr(flags["external-id"]),
+		byok: flags.byok === undefined ? undefined : flagBool(flags.byok),
+		ledger_scope: flags["ledger-scope"] === undefined ? undefined : flagBool(flags["ledger-scope"]),
 	});
 }
 
@@ -3140,7 +3142,7 @@ async function cmdAdminSpend(ctx) {
 			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]'
+					'Usage: admin spend import <file.csv> [--vendor Concentrate] [--area kernels] [--category ai_model] [--basis billed|estimated] [--ref "…"] [--ledger-key \"Main Concentrate Key\"] [--dry-run]'
 				);
 			const body = compact({
 				csv: readFileSync(path, "utf8"),
@@ -3149,7 +3151,7 @@ async function cmdAdminSpend(ctx) {
 				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,
+				ledger_key: flagStr(flags["ledger-key"]),
 				dry_run: flagBool(flags["dry-run"]) || undefined,
 			});
 			const result = await staffPost(ctx, `${SPEND}/import`, body);
@@ -3157,8 +3159,8 @@ async function cmdAdminSpend(ctx) {
 				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`
+					(result.ledgerScopeRows
+						? `; ${result.ledgerScopeRows} rows on the ledger's own key kept as ledger-scope (reconciled, not added)`
 						: "") +
 					(flagBool(flags["dry-run"]) ? " (dry run, nothing written)" : "")
 			);
@@ -3171,6 +3173,38 @@ async function cmdAdminSpend(ctx) {
 			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>");
@@ -3179,6 +3213,85 @@ async function cmdAdminSpend(ctx) {
 			printResult(io, flags, result);
 			return 0;
 		}
+		case "reconcile": {
+			const params = new URLSearchParams(compact({ from: flagStr(flags.from), to: flagStr(flags.to) }));
+			const result = await staffRequest(ctx, "GET", `${SPEND}/reconcile${params.size ? `?${params}` : ""}`);
+			printResult(io, flags, result, (r) =>
+				[
+					`${r.window.from} → ${r.window.to}: ${r.rows.filter((x) => x.flag).length} of ${r.rows.length} checks flagged`,
+					...r.rows.map(
+						(x) =>
+							`${x.flag ? "⚑" : " "} ${x.label.slice(0, 44).padEnd(44)} ours ${usd(x.ours.value).padStart(10)}  theirs ${usd(x.theirs.value).padStart(10)}  ${x.diffPct === null ? "" : `${x.diffPct > 0 ? "+" : ""}${x.diffPct}%`}`
+					),
+					...r.notes.map((n) => `  · ${n}`),
+				].join("\n")
+			);
+			return 0;
+		}
+		case "pnl": {
+			const params = new URLSearchParams(
+				compact({
+					range: oneOf(flags, "range", SPEND_RANGES),
+					from: flagStr(flags.from),
+					to: flagStr(flags.to),
+				})
+			);
+			const result = await staffRequest(ctx, "GET", `${SPEND}/pnl${params.size ? `?${params}` : ""}`);
+			printResult(io, flags, result, (p) =>
+				[
+					`${p.range.from} → ${p.range.to}: revenue ${usd(p.totals.revenue)} (${p.revenueSource}) · cost ${usd(p.totals.cost.total)} · margin ${usd(p.totals.margin)}${p.totals.marginPct === null ? "" : ` (${p.totals.marginPct}%)`}`,
+					`  MRR ${usd(p.totals.mrr)} · invoiced ${usd(p.totals.invoiced)} · owed ${usd(p.totals.owed)} · Stripe fees ${usd(p.totals.stripeFees)}`,
+					"",
+					...p.lines.map(
+						(l) =>
+							`  ${l.label.slice(0, 46).padEnd(46)} rev ${usd(l.revenue).padStart(9)}  cost ${usd(l.cost).padStart(9)}  margin ${usd(l.margin).padStart(10)}`
+					),
+				].join("\n")
+			);
+			return 0;
+		}
+		case "reference": {
+			const vendor = flagStr(flags.vendor);
+			const metric = flagStr(flags.metric);
+			const value = flagNum(flags.value);
+			const from = flagStr(flags.from);
+			const to = flagStr(flags.to) ?? from;
+			const ref = flagStr(flags.ref);
+			if (positionals[1] !== "add" || !vendor || !metric || value === undefined || !from || !ref) {
+				throw new CliError(
+					'Usage: admin spend reference add --vendor Concentrate [--key "Writing Kernels v2"] --metric billed_usd --value 17324.24 --from 2026-09-10 --to 2026-10-09 --ref "Concentrate dashboard 2026-10-09"'
+				);
+			}
+			const result = await staffPost(
+				ctx,
+				`${SPEND}/references`,
+				compact({
+					vendor,
+					key_label: flagStr(flags.key),
+					metric,
+					value,
+					period_start: from,
+					period_end: to,
+					source_ref: ref,
+					note: flagStr(flags.note),
+				})
+			);
+			ok(ctx, `Recorded ${metric} ${value} for ${vendor}${flags.key ? ` (${flagStr(flags.key)})` : ""}.`);
+			printResult(io, flags, result);
+			return 0;
+		}
+		case "stripe-sync": {
+			const from = flagStr(flags.from);
+			const to = flagStr(flags.to);
+			if (!from || !to) throw new CliError("Usage: admin spend stripe-sync --from 2026-01-01 --to 2026-10-09");
+			const result = await staffPost(ctx, `${SPEND}/stripe-sync`, { from, to });
+			ok(
+				ctx,
+				`Stripe ${result.status}: ${result.transactions ?? 0} balance transactions, fees filed for ${result.feeDays ?? 0} days.`
+			);
+			printResult(io, flags, result);
+			return 0;
+		}
 		case "services": {
 			const result = await staffRequest(ctx, "GET", `${SPEND}/services`);
 			printResult(io, flags, result, formatSpendServices);
@@ -3208,7 +3321,7 @@ async function cmdAdminSpend(ctx) {
 		}
 		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> … | remove <entry-id> | services | service <slug> --owner … --monthly …"
+				"Usage: admin spend summary [--range day|week|month|year | --from D --to D] [--grain day|week|month] | reconcile [--from D --to D] | pnl [--range …] | reference add … | stripe-sync --from D --to D | 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 …"
 			);
 	}
 }

package/package.json

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