@letterstory/cli 0.102.1 → 0.102.3

package/README.md

@@ -815,6 +815,12 @@ here can SEND email or spend money, so they refuse unknown flags instead of igno
 
 ```bash
 # Mailers
+letterstory mail vercel-key set --token-file - --team team_AbC123   # optional: buy domains on YOUR Vercel team (token on stdin)
+letterstory mail registrant --first-name Dana --last-name Lee --email d@acme.com --phone +1.4155550100 \
+  --address "1 Main St" --city Oakland --state CA --zip 94607 --country US   # WHOIS owner for purchases on that key
+letterstory mailers quote acme-mail.com                      # price it first: nothing is bought
+letterstory mailers launch acme-mail.com --mailer "hello:Hello Team" --forward-to me@acme.com --yes
+letterstory mailers domains                                  # every domain: setup job, mailers, warmup
 letterstory mailers list [--domain acme.com]                 # status + daily send limit
 letterstory mailers domain <owned-domain-id>                 # provisioning stage, DNS, mailers on it
 letterstory mailers messages <mailer-id> [--folder inbox|sent|all] [--limit 25]   # envelopes
@@ -828,9 +834,6 @@ letterstory mailers suppressions [list] [--reason bounce] [--limit 100]
 letterstory mailers suppressions add person@x.com --reason manual --note "asked to stop"
 letterstory mailers suppressions remove person@x.com         # only 'manual' entries; opt-outs stay
 
-# Launching buys a domain (up to $30) and the mailboxes, so it is a tool call, not a command:
-letterstory call launch_mailers --args '{"domain":"acme-mail.com","mailers":[{"local_part":"hello"}],"consent_attested":true,"mail_from_postal_address":"…"}'
-
 # Org-level mail settings
 letterstory mail connections                                 # connected mailboxes, key + postal address status
 letterstory mail postal-address "123 Main St, Portland, OR 97201"   # CAN-SPAM footer

package/lib/cli.mjs

@@ -60,7 +60,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.102.1";
+export const VERSION = "0.102.3";
 
 // 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
@@ -71,6 +71,11 @@ export const BOOLEAN_FLAGS = new Set([
 	"unfold",
 	// site map: do not start an audit for a host that has none.
 	"no-audit",
+	// site refresh / observe: the loop's switches.
+	"force-map",
+	"force-audit",
+	"skip-observe",
+	"ignore-budget",
 	// lede library update / lede proposals accept: clear or drop the line's condition.
 	"no-condition",
 	// prospects update: clear the HeyReach LinkedIn-reply marker.
@@ -178,6 +183,10 @@ export const BOOLEAN_FLAGS = new Set([
 	"no-notify-staff",
 	"no-opt-out-footer",
 	"no-postal-address-footer",
+	// `mailers launch … --no-warmup` / `--warmup` / `--consent`: value-less switches.
+	"no-warmup",
+	"warmup",
+	"consent",
 	"no-redesign",
 	"no-test-mode",
 	"no-unsubscribe-links",
@@ -1091,7 +1100,13 @@ Prospects (who you write to):
            [--first-name] [--last-name] [--title] [--company] [--website] [--linkedin] [--school]
            [--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 (the sending mailboxes):
+  mailers quote <domain>                               Price a launch domain (read-only, nothing bought)
+  mailers launch <domain> --mailer <name>[:<Display Name>]... --yes
+           [--forward-to <email>] [--no-warmup] [--postal-address "<addr>"] [--consent] [--customer-ref <r>]
+                                                       Buy or reuse the domain, create mailers, warm them up
+                                                       (a net-new domain is a real, auto-renewing purchase)
+  mailers domains                                      Every domain you own: mail status, setup job, mailers
   mailers list [--domain <apex>]                       Your mailers + status + daily send limit
   mailers domain <owned-domain-id>                     Provisioning stage, DNS state, mailers on a domain
   mailers messages <mailer-id> [--folder all|inbox|sent] [--limit <n>]
@@ -1110,6 +1125,12 @@ Mailers (the sending mailboxes; launching one buys a domain, so use: call launch
 Mail:
   mail connections                                     Connected mailboxes, Google connect, Vercel key + mailing address status
   mail postal-address "<address>"                      Set the org's CAN-SPAM mailing address (email footers)
+  mail vercel-key set (--token <t> | --token-file <path|->) [--team <team_id>]
+                                                       Buy and own mail domains on your Vercel account / team
+  mail vercel-key remove --yes                         Future purchases go back to Letterstory's account
+  mail registrant --first-name <f> --last-name <l> --email <e> --phone +1.4155551234
+           --address <a> [--address2 <a>] --city <c> --state <s> --zip <z> --country US [--company <c>]
+                                                       WHOIS registrant for purchases on your Vercel key
 
 Insights:
   insights summary [--period …] [--part <block>]...    Measure Overview: AI named/cited rates, share of voice, search, targets
@@ -1127,13 +1148,16 @@ Insights:
 
 The Site (one model of your whole marketing site, keyed by host and path):
   site list                                            Mapped hosts, and hosts you already have elsewhere
-  site map <host> [--sitemap <url>] [--max-pages <n>] [--no-audit]
+  site map <host> [--sitemap <url>] [--max-pages <n>] [--no-audit] [--relation owned|watched]
                                                        Map a host from its sitemap; starts an audit if it has none
+  site refresh <host> [--force-map] [--force-audit] [--skip-observe]
+                                                       Run the daily loop now: re-map, re-audit, signals, Jev
+  site unmap <host>                                    Remove a host and everything hanging off it
   site tree <host> [path] [--depth <n>] [--unfold]     The tree one folder at a time, one item per node
   site page <host> <path>                              One page: facts, bindings, raw URLs, open items
-  site observations <host> [path] [--state open|dismissed|resolved] [--tone risk|warn|info]
+  site observations <host> [path] [--state open|dismissed|resolved] [--tone risk|warn|info] [--key <k>] [--since <iso>] [--min-reach <0..1>]
   site observe <host> [path] [--max-pages <n>]         Jev pass: meta accuracy, title, outdated
-  site dismiss <host> <observation-id> --reason <why> [--decision dismiss|reopen]
+  site dismiss <host> <observation-id> --reason <why> [--kind not_relevant|already_handled|wrong|later] [--decision dismiss|reopen]
   site families <host> [path] [--state suggested|tracked|dismissed]
   site decide-family <family-id> [--decision tracked|dismissed] [--reason <why>] [--name <n>]
                      [--include <path>]... [--exclude <path>]...

package/lib/commands/admin.mjs

@@ -2810,6 +2810,43 @@ async function cmdAdminCrmCapture(ctx, paths) {
 		})
 	);
 	if (flagBool(flags.json)) return printResult(io, flags, r);
+	for (const line of captureSummary(r)) io.log(line);
+}
+
+/** What a batch entry's status says, in the CLI's words. */
+const BATCH_STATUS = {
+	would_match: "would add to",
+	would_create: "would create",
+	matched: "added to",
+	created: "created",
+	duplicate: "already in",
+	unidentified: "not found",
+	not_found: "no account",
+	failed: "didn't save",
+};
+
+/**
+ * A capture result as lines (pure). A single capture is one line and what it
+ * read; one that became several entries — people on a list, or notes on
+ * several accounts from one roundup — is a line per entry, so the person sees
+ * where each went (the CRM's paste box and the Slack reply list the same).
+ */
+export function captureSummary(r) {
+	if (r.batch) {
+		const width = Math.max(...r.batch.map((b) => (BATCH_STATUS[b.status] ?? b.status).length), 0);
+		return [
+			`${r.dryRun ? "would save" : "saved"} ${r.accountName ?? `${r.batch.length} entries`}`,
+			...r.batch.map((b) => {
+				const status = (BATCH_STATUS[b.status] ?? b.status).padEnd(width);
+				const where = b.accountName ?? b.companyName ?? "?";
+				const extra =
+					b.status === "failed" || b.status === "not_found" || b.status === "unidentified"
+						? b.why
+						: b.headline;
+				return `  ${status}  ${b.name} → ${where}${b.accountUrl ? `  ${b.accountUrl}` : ""}${extra ? `  — ${extra}` : ""}`;
+			}),
+		];
+	}
 	const verb = r.dryRun
 		? r.accountId
 			? "would add to"
@@ -2819,15 +2856,16 @@ async function cmdAdminCrmCapture(ctx, paths) {
 			: r.accountCreated
 				? "created"
 				: "added to";
-	io.log(
-		`${verb} ${r.accountName ?? "a new account"}${r.accountUrl ? `  ${r.accountUrl}` : ""}${r.matchedVia ? `  (via ${r.matchedVia})` : ""}`
-	);
+	const lines = [
+		`${verb} ${r.accountName ?? "a new account"}${r.accountUrl ? `  ${r.accountUrl}` : ""}${r.matchedVia ? `  (via ${r.matchedVia})` : ""}`,
+	];
 	if (r.read) {
-		io.log(`  ${r.read.title}`);
+		lines.push(`  ${r.read.title}`);
 		if (r.contacts.length)
-			io.log(`  contacts: ${r.contacts.map((p) => p.name + (p.email ? ` <${p.email}>` : "")).join(", ")}`);
-		if (r.read.notes) io.log(`  notes: ${r.read.notes}`);
+			lines.push(`  contacts: ${r.contacts.map((p) => p.name + (p.email ? ` <${p.email}>` : "")).join(", ")}`);
+		if (r.read.notes) lines.push(`  notes: ${r.read.notes}`);
 	}
+	return lines;
 }
 
 /**
@@ -2845,6 +2883,7 @@ async function cmdAdminCrmCapture(ctx, paths) {
  *   outreach catch-up [--dry-run]                    handle #launch-outreach posts the bot missed
  *   outreach set <id> [--reached|--not-reached] [--response "…" --tone positive]
  *                [--owner-id <uuid>] [--channel …] [--ask …] [--draft "…"] [--archive|--restore]
+ *                [--timezone Europe/London|PT|""]   "" goes back to the guess from their location
  */
 async function cmdAdminCrmOutreach(ctx, args) {
 	const { flags, io } = ctx;
@@ -2952,6 +2991,8 @@ async function cmdAdminCrmOutreach(ctx, args) {
 				relationship: flagStr(flags.relationship),
 				draftMessage: flagStr(flags.draft),
 				notes: flagStr(flags.notes),
+				// "Europe/London", or "PT" / "eastern"; "" clears it back to the guess from their location.
+				timezone: flagStr(flags.timezone),
 				archived: flagBool(flags.archive) ? true : flagBool(flags.restore) ? false : undefined,
 			});
 			const r = await staffRequest(ctx, "PATCH", `${CRM}/outreach/${id}`, body);

package/lib/commands/outbound.mjs

@@ -393,8 +393,62 @@ export const ARGS = {
 	set_mail_postal_address: {
 		mail_postal_address: { positional: 0, label: "address", required: true },
 	},
+	list_mail_domains: {},
+	quote_mail_domain: {
+		domain: { positional: 0, label: "domain", required: true },
+	},
+	launch_mailers: {
+		domain: { positional: 0, label: "domain", required: true },
+		mailers: { value: launchMailerRows },
+		customer_ref: "customer-ref",
+		forward_to: "forward-to",
+		warmup: { flag: "warmup", type: "bool", negate: "no-warmup" },
+		consent_attested: { flag: "consent", type: "bool" },
+		mail_from_postal_address: "postal-address",
+	},
+	set_vercel_key: {
+		// --token-file <path|-> keeps the token out of shell history.
+		token: {
+			value: (flags) => {
+				const token = readTextInput(flags, "token", "token-file")?.trim();
+				if (!token) throw new CliError("Pass --token <vercel-token> (or --token-file <path|->)");
+				return token;
+			},
+		},
+		team_id: "team",
+	},
+	remove_vercel_key: {},
+	set_registrant_contact: {
+		registrant_contact: {
+			object: {
+				firstName: "first-name",
+				lastName: "last-name",
+				email: "email",
+				phone: "phone",
+				address1: "address",
+				address2: "address2",
+				city: "city",
+				state: "state",
+				zip: "zip",
+				country: "country",
+				companyName: "company",
+			},
+		},
+	},
 };
 
+// `--mailer <name>[:<Display Name>]`, repeatable: the addresses a launch creates.
+function launchMailerRows(flags) {
+	const rows = flagList(flags.mailer).map((raw) => {
+		const at = raw.indexOf(":");
+		const localPart = (at < 0 ? raw : raw.slice(0, at)).trim();
+		const displayName = at < 0 ? "" : raw.slice(at + 1).trim();
+		return displayName ? { local_part: localPart, display_name: displayName } : { local_part: localPart };
+	});
+	if (rows.length === 0) throw new CliError("Pass at least one --mailer <name>[:<Display Name>]");
+	return rows;
+}
+
 // `message` may be a function of the tool's result, for a line that reports what actually happened.
 async function run(ctx, tool, message) {
 	refuseUnknownFlags(ctx, ARGS[tool]);
@@ -639,7 +693,7 @@ async function prospectsColumns(ctx, sub) {
 	}
 }
 
-const MAILERS_USAGE = `Usage: mailers <list|domain|messages|message|forward|warmup|limit|retire|suppressions>`;
+const MAILERS_USAGE = `Usage: mailers <list|domains|domain|quote|launch|messages|message|forward|warmup|limit|retire|suppressions>`;
 
 export async function cmdMailers(ctx) {
 	const sub = ctx.positionals[0];
@@ -648,8 +702,23 @@ export async function cmdMailers(ctx) {
 		case "list":
 		case "ls":
 			return run(rest, "list_mailers");
+		case "domains":
+			return run(rest, "list_mail_domains");
 		case "domain":
 			return run(rest, "get_mailer_domain_status");
+		case "quote":
+			return run(rest, "quote_mail_domain");
+		case "launch": {
+			// A net-new domain is a real purchase, so a launch needs --yes (quote it first).
+			if (!rest.flags.yes) {
+				const domain = flagStr(rest.positionals[0]) ?? "<domain>";
+				ctx.io.error(
+					`Launching may BUY ${domain} (auto-renewing). Check the price with: ${ctx.bin} mailers quote ${domain}\nThen re-run with --yes to confirm.`
+				);
+				return 1;
+			}
+			return run(rest, "launch_mailers", (r) => `Mail setup started on ${r?.domain ?? "the domain"}.`);
+		}
 		case "messages":
 			return run(rest, "list_mailer_messages");
 		case "message":
@@ -708,7 +777,32 @@ export async function cmdMail(ctx) {
 			return run(rest, "get_mail_connections");
 		case "postal-address":
 			return run(rest, "set_mail_postal_address", "Mailing address saved.");
+		case "vercel-key": {
+			const action = rest.positionals[0];
+			const inner = { ...rest, positionals: rest.positionals.slice(1) };
+			if (action === "set") {
+				return run(inner, "set_vercel_key", (r) =>
+					r?.team_id
+						? `Vercel key saved: new domains are bought in team ${r.team_id}.`
+						: "Vercel key saved: new domains are bought in the token's personal account."
+				);
+			}
+			if (action === "remove") {
+				if (!inner.flags.yes) {
+					ctx.io.error(
+						`Removing the key sends future purchases back to Letterstory's account and drops the registrant contact. Re-run with --yes to confirm: ${ctx.bin} mail vercel-key remove --yes`
+					);
+					return 1;
+				}
+				return run(inner, "remove_vercel_key", "Vercel key removed.");
+			}
+			throw new CliError(`Unknown vercel-key action: ${action ?? "(none)"}. Try: set, remove`);
+		}
+		case "registrant":
+			return run(rest, "set_registrant_contact", "Registrant contact saved.");
 		default:
-			throw new CliError(`Unknown mail subcommand: ${sub ?? "(none)"}. Try: connections, postal-address`);
+			throw new CliError(
+				`Unknown mail subcommand: ${sub ?? "(none)"}. Try: connections, postal-address, vercel-key, registrant`
+			);
 	}
 }

package/lib/commands/shared.mjs

@@ -128,16 +128,22 @@ export function valueSourceFlags(value) {
  */
 export function refuseUnknownFlags(ctx, argsMap, own = []) {
 	const allowed = new Set([...GLOBAL_FLAGS, ...own]);
-	for (const source of Object.values(argsMap ?? {})) {
-		if (typeof source === "string") allowed.add(source);
-		else if (Array.isArray(source)) source.forEach((f) => allowed.add(f));
-		else if (source && typeof source === "object" && source.flag) {
-			allowed.add(source.flag);
-			if (source.negate) allowed.add(source.negate);
-		} else if (source && typeof source === "object" && typeof source.value === "function") {
-			valueSourceFlags(source.value).forEach((f) => allowed.add(f));
+	const collect = (map) => {
+		for (const source of Object.values(map ?? {})) {
+			if (typeof source === "string") allowed.add(source);
+			else if (Array.isArray(source)) source.forEach((f) => allowed.add(f));
+			else if (source && typeof source === "object" && source.flag) {
+				allowed.add(source.flag);
+				if (source.negate) allowed.add(source.negate);
+			} else if (source && typeof source === "object" && typeof source.value === "function") {
+				valueSourceFlags(source.value).forEach((f) => allowed.add(f));
+			} else if (source && typeof source === "object" && source.object) {
+				// A nested `{ object }` source reads its own flags (e.g. a contact's fields).
+				collect(source.object);
+			}
 		}
-	}
+	};
+	collect(argsMap);
 	const unknown = Object.keys(ctx.flags).filter((f) => !allowed.has(f));
 	if (unknown.length) {
 		throw new CliError(

package/lib/commands/site.mjs

@@ -41,7 +41,15 @@ const ARGS = {
 		sitemap_url: "sitemap",
 		max_pages: { flag: "max-pages", type: "num" },
 		audit: { flag: "no-audit", type: "bool", invert: true },
+		relation: { flag: "relation", enum: ["owned", "watched"] },
 	},
+	refresh_site: {
+		host: { positional: 0, required: true, label: "host" },
+		force_map: { flag: "force-map", type: "bool" },
+		force_audit: { flag: "force-audit", type: "bool" },
+		skip_observe: { flag: "skip-observe", type: "bool" },
+	},
+	unmap_site: { host: { positional: 0, required: true, label: "host" } },
 	get_site_tree: {
 		host: { positional: 0, required: true, label: "host" },
 		path: { positional: 1, label: "path" },
@@ -58,18 +66,23 @@ const ARGS = {
 		status: { flag: "state", enum: ["open", "dismissed", "resolved"] },
 		tone: { flag: "tone", enum: ["ok", "warn", "risk", "info"] },
 		source: "source",
+		key: "key",
+		since: "since",
+		min_reach: { flag: "min-reach", type: "num" },
 		limit: { flag: "limit", type: "num" },
 	},
 	observe_site: {
 		host: { positional: 0, required: true, label: "host" },
 		path: { positional: 1, label: "path" },
 		max_pages: { flag: "max-pages", type: "num" },
+		ignore_budget: { flag: "ignore-budget", type: "bool" },
 	},
 	dismiss_site_observation: {
 		host: { positional: 0, required: true, label: "host" },
 		observation_id: { positional: 1, required: true, label: "observation-id" },
 		decision: { flag: "decision", enum: ["dismiss", "reopen"] },
 		reason: "reason",
+		reason_kind: { flag: "kind", enum: ["not_relevant", "already_handled", "wrong", "later"] },
 	},
 	list_site_families: {
 		host: { positional: 0, required: true, label: "host" },
@@ -113,6 +126,10 @@ export async function cmdSite(ctx) {
 			return siteList(rest);
 		case "map":
 			return siteMap(rest);
+		case "refresh":
+			return siteRefresh(rest);
+		case "unmap":
+			return siteUnmap(rest);
 		case "tree":
 			return siteTree(rest);
 		case "page":
@@ -135,7 +152,7 @@ export async function cmdSite(ctx) {
 			return siteDecide(rest);
 		default:
 			throw new CliError(
-				`Unknown site subcommand: ${sub ?? "(none)"}. Try: list, map, tree, page, observations, observe, dismiss, families, decide-family, proposals, propose, decide`
+				`Unknown site subcommand: ${sub ?? "(none)"}. Try: list, map, refresh, unmap, tree, page, observations, observe, dismiss, families, decide-family, proposals, propose, decide`
 			);
 	}
 }
@@ -187,6 +204,24 @@ async function siteMap(ctx) {
 	return 0;
 }
 
+async function siteRefresh(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.refresh_site);
+	const result = await client.callTool("refresh_site", argsFromFlags(ARGS.refresh_site, flags, ctx.positionals));
+	ok(ctx, result.message);
+	printResult(io, flags, result.report, (r) => r.skipped.map((s) => `  skipped: ${s}`).join("\n"));
+	return 0;
+}
+
+async function siteUnmap(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.unmap_site);
+	const result = await client.callTool("unmap_site", argsFromFlags(ARGS.unmap_site, flags, ctx.positionals));
+	ok(ctx, result.message);
+	printResult(io, flags, result, () => "");
+	return 0;
+}
+
 async function siteTree(ctx) {
 	const { client, flags, io } = ctx;
 	refuseUnknownFlags(ctx, ARGS.get_site_tree);

package/lib/documents.mjs

@@ -83,6 +83,8 @@ export const JSON_ARG_FLAG_PAIRS = [
 	["csv", "csv-file"],
 	// A site proposal's tool input, parsed as JSON (site.mjs proposalInput).
 	["input", "input-file"],
+	// A Vercel API token read verbatim, so it stays out of shell history (outbound.mjs mail vercel-key set).
+	["token", "token-file"],
 ];
 
 /** Lower-case extension without the dot. */

package/package.json

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