@letterstory/cli 0.93.1 → 0.94.0

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.94.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",
@@ -1016,6 +1019,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 +1051,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 +1092,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 +1192,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/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.94.0",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",