@letterstory/cli 0.75.0 → 0.76.1

package/README.md

@@ -749,6 +749,14 @@ AI visibility and page access — the Measure tabs' reads, for scripts and agent
 # search, actions, targets — `ai` is the slow one on a large org.
 letterstory insights summary [--period 14d|30d|90d] [--part <block>]...
 
+# GEO → Competitors: every tracked brand's share of mentions (one per brand per
+# answer) on the window, whether each is moving (the same question on the same
+# engine in both windows — the only up/down read), the question × engine cells
+# behind it, the line per engine, each question's top rival, and every dated
+# change under the number. --period sets the windows: 14d → last 2 complete
+# weeks vs the 2 before, 30d → 4 vs 4, 90d → 13 vs 13.
+letterstory insights competitors [--period 14d|30d|90d]
+
 # The AI Visibility Bank: which questions named you, cited your pages, or both (a
 # breakthrough). All time unless --period; --source picks the phantom network
 # (default), your marketing site, or the whole portfolio; --phantom narrows to

package/lib/cli.mjs

@@ -56,7 +56,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.75.0";
+export const VERSION = "0.76.1";
 
 // 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,8 +582,12 @@ 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]
@@ -918,6 +922,7 @@ Mail:
 
 Insights:
   insights summary [--period …] [--part <block>]...    Measure Overview: AI named/cited rates, share of voice, search, targets
+  insights competitors [--period 14d|30d|90d]          GEO → Competitors: share of mentions per brand, is it moving, by engine/question
   insights site [--period 14d|30d|90d] [--collection <uuid>]
   insights post <article-id> [--period 14d|30d|90d]
   insights top [--period 14d|30d|90d] [--collection <uuid>] [--limit <n>] [--sort clicks|impressions]

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|usage|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)" : "")
 			);
@@ -3211,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);
@@ -3240,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> … | usage <events.json> | 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/lib/commands/insights.mjs

@@ -1,7 +1,8 @@
 // `insights` — Search Console impressions/clicks across the phantom network, at the
 // network, single-post, and top-posts levels (ported from phantomstory-cli's
-// insights.ts); plus Measure's Overview (`summary`), AI Visibility Bank (`bank`)
-// and phantom Page Access (`access`) — the same reads the web app's Measure tabs render.
+// insights.ts); plus Measure's Overview (`summary`), GEO → Competitors
+// (`competitors`), AI Visibility Bank (`bank`) and phantom Page Access (`access`)
+// — the same reads the web app's Measure tabs render.
 
 import { CliError } from "../client.mjs";
 import { flagStr, flagNum, requirePositional, printResult, compact, argsFromFlags } from "./shared.mjs";
@@ -23,6 +24,9 @@ export const ARGS = {
 		period: { flag: "period", enum: PERIODS },
 		parts: { flag: "part", type: "list" },
 	},
+	get_share_of_voice_detail: {
+		period: { flag: "period", enum: PERIODS },
+	},
 };
 
 export async function cmdInsights(ctx) {
@@ -41,9 +45,11 @@ export async function cmdInsights(ctx) {
 			return call(rest, "get_page_access");
 		case "summary":
 			return call(rest, "get_measure_summary");
+		case "competitors":
+			return call(rest, "get_share_of_voice_detail");
 		default:
 			throw new CliError(
-				`Unknown insights subcommand: ${sub ?? "(none)"}. Try: summary, site, post, top, bank, access`
+				`Unknown insights subcommand: ${sub ?? "(none)"}. Try: summary, competitors, site, post, top, bank, access`
 			);
 	}
 }

package/package.json

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