@letterstory/cli 0.93.1 → 0.95.0

package/README.md

@@ -353,6 +353,7 @@ long-running agent can watch the fleet on a schedule without a browser.
 # every client against itself on share of voice, mention rate and page access, with what we
 # did for it. Needs fleet:read; `run` and `ask` spend Fable tokens and need fleet:query.
 letterstory admin patterns --period 30d
+letterstory admin patterns kernels --by version --outcome impressions14   # what each kernel/version change did
 letterstory admin patterns reports            # Fable's weekly reports and runs, newest first
 letterstory admin patterns report <id>        # one report's markdown
 letterstory admin patterns run                # a report now (takes minutes)

package/lib/cli.mjs

@@ -54,10 +54,11 @@ import {
 	cmdEvals,
 	cmdOfferings,
 	cmdTargets,
+	cmdVisits,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.93.1";
+export const VERSION = "0.95.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. Every `type: "bool"` flag (and its
@@ -66,6 +67,8 @@ export const BOOLEAN_FLAGS = new Set([
 	"json",
 	// lede library update / lede proposals accept: clear or drop the line's condition.
 	"no-condition",
+	// prospects update: clear the HeyReach LinkedIn-reply marker.
+	"clear-linkedin-reply",
 	"yes",
 	"confirm-missing-target",
 	"no-wait",
@@ -657,6 +660,10 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        Client patterns: every client's share of voice,
                                                        mention rate and page access against itself, with
                                                        what we did for it. Needs fleet:read.
+  admin patterns kernels [--by version|family] [--outcome cited14|read14|named|impressions14|clicks14|cited28|impressions28]
+                                                       What each kernel and version change did: the client's
+                                                       change minus clients that held still, pooled by
+                                                       transition. Needs fleet:read.
   admin patterns reports [--kind reports|weekly|run|ask] | report <id>
                                                        Fable's weekly reports, runs and Ask Fable answers.
   admin patterns run | ask "<question>"                Run a Fable report now, or ask Fable a question
@@ -1016,6 +1023,9 @@ Sequences (multi-step cold email sent from your mailers; approving or enrolling
   sequences cakes sync                                 Re-read the connected Daymaker account now
   sequences cakes connect --daymaker-key <dm_live_…>   Connect the org's Daymaker account (key checked, stored encrypted)
   sequences cakes disconnect                           Forget the key and remove the webhook
+  sequences heyreach                                   Whether the org has a HeyReach webhook (LinkedIn replies stop email)
+  sequences heyreach rotate                            Make (or rotate) the HeyReach webhook URL; staff org admins
+  sequences heyreach disconnect                        Remove the HeyReach webhook URL
 
 Dispatches (the named review desks a sequence's review stage queues to):
   dispatches list                                      Desks + how many emails each has queued
@@ -1045,7 +1055,7 @@ Prospects (who you write to):
   prospects columns delete <column-id> --yes
   prospects update <prospect-id> [--status new|contacted|replied|unsubscribed|archived] [--name <n>]
            [--first-name] [--last-name] [--title] [--company] [--website] [--linkedin] [--school]
-           [--city] [--country] [--years] [--notes] [--custom key=value]...
+           [--city] [--country] [--years] [--notes] [--custom key=value]... [--clear-linkedin-reply]
 
 Mailers (the sending mailboxes; launching one buys a domain, so use: call launch_mailers):
   mailers list [--domain <apex>]                       Your mailers + status + daily send limit
@@ -1086,6 +1096,15 @@ Feedback (tell us what's broken, missing, unclear, or wanted):
                   [--message <text>|--body <text>|--file <path>|--file -] [--rating 1-5]
                   [--context '<json>']
 
+Visits (Visitors: AI agents reading your site, and AI answers sending people to it):
+  visits [--agent <a>] [--since 7d] [--path '/docs/*'] [--purpose live|index|training|automated_browser] [--site <id>]
+                                                       Agent visits: per agent, why they came, most-read pages
+  visits citations [--since 30d] [--site <id>]         People who clicked through from ChatGPT, Claude, Perplexity…
+  visits compare <agent-a> <agent-b> [--since 7d] [--path '/docs/*'] [--purpose <p>]
+                                                       Pages one agent read that the other didn't
+  visits export [--since 30d] [--format json|csv] [--table agent_visits|citations]
+  visits sites                                         Your Visitors sites and their install checks
+
 Evals (how the pipeline is doing on your posts, and the regression cases captured from them):
   evals scoreboard [--collection <id>] [--days N]      Every measure by stage: posts, failing, rate
   evals cases [--status open|guarding|proposed|retired|rejected] [--stage research|brief|links|mentions|accuracy|pipeline|shred]
@@ -1177,6 +1196,7 @@ const CLIENT_COMMANDS = {
 	mailers: cmdMailers,
 	feedback: cmdFeedback,
 	evals: cmdEvals,
+	visits: cmdVisits,
 	// Platform-scoped (staff key) — the only commands that act BEFORE an org exists.
 	admin: cmdAdmin,
 };

package/lib/commands/admin.mjs

@@ -4,7 +4,7 @@
 // routes, because they exist precisely to act BEFORE an org exists.
 //
 //   admin ask "which kernels are hooked up to the most clients?" [--sql] [--json]
-//   admin patterns [--period 14d|30d] [--segment "…"] | reports [--kind reports|weekly|run|ask] | report <id> | run | ask "<question>"   (fleet:read / fleet:query)
+//   admin patterns [--period 14d|30d] [--segment "…"] | kernels [--by version|family] [--outcome cited14] | reports [--kind reports|weekly|run|ask] | report <id> | run | ask "<question>"   (fleet:read / fleet:query)
 //   admin experiments list|show|new|update|note|started|spend|conclude|abandon …   (tuning:experiment)
 //   admin tuning-context [--q "<question>"]                                         (tuning:experiment)
 //   admin tuning-import <brief-results.json> [--experiment <id>]                    (tuning:experiment)
@@ -273,6 +273,28 @@ async function cmdAdminPatterns(ctx) {
 			}
 			return;
 		}
+		case "kernels": {
+			const params = new URLSearchParams();
+			if (flagStr(ctx.flags.by)) params.set("by", flagStr(ctx.flags.by));
+			if (flagStr(ctx.flags.outcome)) params.set("outcome", flagStr(ctx.flags.outcome));
+			const result = await staffRequest(ctx, "GET", `${PATTERNS}/kernels${params.size ? `?${params}` : ""}`);
+			if (json) return printResult(ctx.io, ctx.flags, result);
+			const fmt = (v) => (v == null ? "—" : `${v >= 0 ? "+" : "−"}${Math.abs(v).toFixed(3)}`);
+			ctx.io.log(
+				`Kernel changes on ${result.outcome}, by ${result.by} (effect = change minus clients that held still):`
+			);
+			for (const t of result.transitions)
+				ctx.io.log(
+					`  ${`${t.from} → ${t.to}`.padEnd(30)} ${fmt(t.effect)} (${fmt(t.lo)} to ${fmt(t.hi)})  ${t.verdict}  · ${t.swaps} swaps, ${t.clients} clients`
+				);
+			if (!result.transitions.length) ctx.io.log("  none yet");
+			ctx.io.log(`\n${result.by === "version" ? "Versions" : "Kernels"} (descriptive):`);
+			for (const k of result.kernels)
+				ctx.io.log(
+					`  ${k.label.padEnd(16)} ${String(k.posts).padStart(6)} posts  ${String(k.clients).padStart(4)} clients  ${k.outcome ? k.outcome.mean.toFixed(3) : "—"}`
+				);
+			return;
+		}
 		case "reports": {
 			const kind = flagStr(ctx.flags.kind) ?? "reports";
 			const limit = flagStr(ctx.flags.limit) ?? "12";
@@ -312,7 +334,9 @@ async function cmdAdminPatterns(ctx) {
 			return;
 		}
 		default:
-			throw new CliError('Usage: admin patterns [show] | reports | report <id> | run | ask "<question>"');
+			throw new CliError(
+				'Usage: admin patterns [show] | kernels | reports | report <id> | run | ask "<question>"'
+			);
 	}
 }
 

package/lib/commands/outbound.mjs

@@ -190,6 +190,9 @@ export const ARGS = {
 	sync_cakes: {},
 	connect_daymaker: { api_key: { flag: "daymaker-key", required: true } },
 	disconnect_daymaker: {},
+	get_heyreach_webhook: {},
+	rotate_heyreach_webhook: {},
+	disconnect_heyreach_webhook: {},
 	enroll_in_sequence: {
 		sequence_id: { positional: 0, label: "sequence-id", required: true },
 		recipients: { value: readRecipients },
@@ -328,6 +331,7 @@ export const ARGS = {
 		country: "country",
 		years_at_company: "years",
 		notes: "notes",
+		linkedin_replied_at: { value: (flags) => (flags["clear-linkedin-reply"] ? null : undefined) },
 		custom: { value: readCustom },
 	},
 	list_mailers: {
@@ -397,7 +401,7 @@ async function run(ctx, tool, message) {
 	return 0;
 }
 
-const SEQUENCES_USAGE = `Usage: sequences <list|get|create|update|pause|resume|enroll|stop|review|links|cakes>`;
+const SEQUENCES_USAGE = `Usage: sequences <list|get|create|update|pause|resume|enroll|stop|review|links|cakes|heyreach>`;
 const DISPATCHES_USAGE = `Usage: dispatches <list|create|rename|delete>`;
 
 // Dispatches: the named review desks a sequence's review stage queues to.
@@ -478,6 +482,21 @@ export async function cmdSequences(ctx) {
 					return run(rest, "list_cakes");
 			}
 		}
+		case "heyreach": {
+			const heyreachCtx = { ...rest, positionals: rest.positionals.slice(1) };
+			switch (rest.positionals[0]) {
+				case "rotate":
+					return run(
+						heyreachCtx,
+						"rotate_heyreach_webhook",
+						"HeyReach webhook URL made; paste it into HeyReach."
+					);
+				case "disconnect":
+					return run(heyreachCtx, "disconnect_heyreach_webhook", "HeyReach webhook removed.");
+				default:
+					return run(rest, "get_heyreach_webhook");
+			}
+		}
 		default:
 			throw new CliError(`Unknown sequences subcommand: ${sub ?? "(none)"}. ${SEQUENCES_USAGE}`);
 	}

package/lib/commands/visits.mjs

@@ -0,0 +1,175 @@
+// `visits` — Visitors from a terminal: which AI agents read your site, why they
+// came, which AI answers sent people to you, and two agents side by side. Thin
+// wrappers over the visitors_* tools (visitors_get_agent_visits,
+// visitors_get_citations, visitors_compare_agents, visitors_export, …), the same
+// lib functions the app and lettervisit.com/mcp call.
+//
+//   letterstory visits --agent claude --since 7d
+//   letterstory visits compare chatgpt claude --path '/docs/*' --since 7d
+//   letterstory visits citations --since 30d
+//   letterstory visits export --since 30d --format csv
+//   letterstory visits sites
+
+import { CliError } from "../client.mjs";
+import { flagStr, printResult, argsFromFlags } from "./shared.mjs";
+
+const PURPOSES = ["live", "index", "training", "automated_browser", "unknown"];
+
+const days = { value: (flags) => sinceDays(flags.since) };
+
+export const ARGS = {
+	visitors_list_sites: {},
+	visitors_get_agent_visits: {
+		site_id: "site",
+		days,
+		agent: "agent",
+		path: "path",
+		purpose: { flag: "purpose", enum: PURPOSES },
+	},
+	visitors_get_citations: { site_id: "site", days },
+	visitors_compare_agents: {
+		site_id: "site",
+		a: { positional: 0, label: "agent-a (e.g. chatgpt)", required: true },
+		b: { positional: 1, label: "agent-b (e.g. claude)", required: true },
+		days,
+		path: "path",
+		purpose: { flag: "purpose", enum: PURPOSES },
+	},
+	visitors_export: { site_id: "site", days, format: { flag: "format", enum: ["json", "csv"] } },
+};
+
+/** `7d`, `7`, `2w` → days (1-90). Absent → undefined (the tool's default, 30). */
+export function sinceDays(v) {
+	const s = flagStr(v);
+	if (!s) return undefined;
+	const m = /^(\d+)\s*([dw]?)$/i.exec(s.trim());
+	if (!m) throw new CliError(`--since takes days, e.g. 7d, 30 or 2w (got "${s}")`);
+	const n = Number(m[1]) * (m[2].toLowerCase() === "w" ? 7 : 1);
+	if (n < 1 || n > 90) throw new CliError("--since must be between 1 and 90 days");
+	return n;
+}
+
+/** Call a visitors_* tool with the args its ARGS map builds from this command's flags. */
+function call(ctx, tool) {
+	return ctx.client.callTool(tool, argsFromFlags(ARGS[tool], ctx.flags, ctx.positionals));
+}
+
+export async function cmdVisits(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case undefined:
+		case "list":
+		case "ls":
+			return visitsList(sub === undefined ? ctx : rest);
+		case "citations":
+			return visitsCitations(rest);
+		case "compare":
+			return visitsCompare(rest);
+		case "export":
+			return visitsExport(rest);
+		case "sites":
+			return visitsSites(rest);
+		default:
+			throw new CliError("Usage: visits [list|citations|compare|export|sites]");
+	}
+}
+
+const PURPOSE_LABELS = {
+	live: "answering a user",
+	index: "search index",
+	training: "training crawl",
+	automated_browser: "browser agent",
+	unknown: "unlabelled",
+};
+
+async function visitsList(ctx) {
+	const { flags, io } = ctx;
+	const result = await call(ctx, "visitors_get_agent_visits");
+	printResult(io, flags, result, (r) => {
+		const lines = [`${r.total} agent visits since ${r.since} (${r.verified} verified)`];
+		const why = Object.entries(r.by_purpose ?? {})
+			.filter(([, n]) => n > 0)
+			.map(([p, n]) => `${PURPOSE_LABELS[p] ?? p} ${n}`);
+		if (why.length) lines.push(`Why: ${why.join(", ")}`);
+		if (r.agents?.length) {
+			lines.push("", "Agents:");
+			for (const a of r.agents)
+				lines.push(`  ${a.agent.padEnd(14)} ${String(a.total).padStart(6)}  (${a.verified} verified)`);
+		}
+		if (r.top_paths?.length) {
+			lines.push("", "Most read:");
+			for (const p of r.top_paths.slice(0, 10)) lines.push(`  ${String(p.total).padStart(6)}  ${p.path}`);
+		}
+		if (!r.total) lines.push("No agent visits in this window. Is the server snippet installed? (visits sites)");
+		return lines.join("\n");
+	});
+	return 0;
+}
+
+async function visitsCitations(ctx) {
+	const { flags, io } = ctx;
+	const result = await call(ctx, "visitors_get_citations");
+	printResult(io, flags, result, (r) => {
+		const lines = [`${r.total} people arrived from an AI answer since ${r.since}`];
+		for (const s of r.by_source ?? [])
+			lines.push(`  ${s.source.padEnd(12)} ${String(s.visits).padStart(6)}  avg ${s.avg_seconds}s`);
+		if (r.top_pages?.length) {
+			lines.push("", "Landing pages:");
+			for (const p of r.top_pages.slice(0, 10)) lines.push(`  ${String(p.visits).padStart(6)}  ${p.path}`);
+		}
+		return lines.join("\n");
+	});
+	return 0;
+}
+
+async function visitsCompare(ctx) {
+	const { flags, io } = ctx;
+	const result = await call(ctx, "visitors_compare_agents");
+	printResult(io, flags, result, (r) => {
+		const lines = [
+			`${r.a.agent}: ${r.a.total} visits on ${r.a.pages} pages · ${r.b.agent}: ${r.b.total} visits on ${r.b.pages} pages (since ${r.since})`,
+		];
+		lines.push("", `Only ${r.a.agent}:`);
+		for (const p of r.only_a) lines.push(`  ${String(p.a).padStart(6)}  ${p.path}`);
+		if (!r.only_a.length) lines.push("  (none)");
+		lines.push("", `Only ${r.b.agent}:`);
+		for (const p of r.only_b) lines.push(`  ${String(p.b).padStart(6)}  ${p.path}`);
+		if (!r.only_b.length) lines.push("  (none)");
+		return lines.join("\n");
+	});
+	return 0;
+}
+
+async function visitsExport(ctx) {
+	const { flags, io } = ctx;
+	const result = await call(ctx, "visitors_export");
+	if (flagStr(flags.format) === "csv" && !flags.json && result.csv) {
+		// --table picks one; default is agent visits (pipe to a file).
+		const table = flagStr(flags.table) ?? "agent_visits";
+		if (table !== "agent_visits" && table !== "citations")
+			throw new CliError("--table is agent_visits or citations");
+		io.log(result.csv[table]);
+		return 0;
+	}
+	io.log(JSON.stringify(result, null, 2));
+	return 0;
+}
+
+async function visitsSites(ctx) {
+	const { flags, io } = ctx;
+	const result = await call(ctx, "visitors_list_sites");
+	printResult(io, flags, result, (r) => {
+		if (!r.sites?.length) return "No Visitors sites yet. Add one at https://lettervisit.com.";
+		return r.sites
+			.map((s) => {
+				const checks = [
+					s.script_seen_at ? "script ✓" : "script ✗",
+					s.server_seen_at ? "server snippet ✓" : "server snippet ✗",
+				].join(", ");
+				return `${s.site_id}  ${s.domain ?? s.name}  (${checks})`;
+			})
+			.join("\n");
+	});
+	return 0;
+}

package/lib/commands.mjs

@@ -41,3 +41,4 @@ export * from "./commands/targets.mjs";
 export * from "./commands/admin.mjs";
 export * from "./commands/feedback.mjs";
 export * from "./commands/evals.mjs";
+export * from "./commands/visits.mjs";

package/package.json

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