@letterstory/cli 0.40.0 → 0.41.0

package/README.md

@@ -367,6 +367,32 @@ The ledger behind Kernel Tuning's Experiments tab
 (docs/architecture/kernel-experiment-agent.md): every question asked of the kernels,
 how it was tested, and what we learned and why.
 
+### Staff: the CRM pipeline
+
+```bash
+# Needs a STAFF key with crm:read (reads) and crm:write (writes). The same routes the
+# crm.letter.dev front end calls with a staff JWT; any /api/superadmin/crm/* route takes
+# the key as x-staff-api-key (GET → crm:read, anything else → crm:write).
+export LETTERSTORY_STAFF_API_KEY=<your staff key with crm:read,crm:write>
+
+letterstory admin crm signals --status new             # the Inbound feed (unmatched signals)
+letterstory admin crm record --source bookface --kind message \
+  --title "Asked about phantoms on Bookface" --name "Jane Doe" --company Acme --domain acme.com
+letterstory admin crm record --source twitter --kind social_engagement \
+  --title "Liked our launch tweet" --name "Pat" --linkedin https://linkedin.com/in/pat
+letterstory admin crm signal <signal-id> qualify       # link/create the account
+letterstory admin crm signal <signal-id> dismiss       # the easy delete (kept, marked)
+letterstory admin crm accounts --stage demo_scheduled  # with likelihood
+letterstory admin crm score <account-id>               # recompute; prints the factors
+```
+
+Every trigger — Cal.com bookings, Circleback recordings, Letterhome dinner RSVPs, RB2B
+visits, and what an agent records here — goes through one intake (`ingestSignal`,
+src/lib/crm/signals-intake.ts), so an agent's signal dedupes against a webhook's exactly
+as two webhooks do. Qualified kinds (booking, call recording, dinner, message, form) link
+or create the account; unqualified ones (a visit, a like) only attach to an existing
+account and otherwise wait in the Inbound feed.
+
 ### Propose, then onboard a phantom
 
 The Fleet wizard's Plan and Name screens as two commands: pick the beat, then the name,

package/lib/cli.mjs

@@ -52,7 +52,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.40.0";
+export const VERSION = "0.41.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.
@@ -556,6 +556,16 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        session (a trial per arm), linked to its
                                                        ledger entry. Written by \`npm run lab --
                                                        publish\` in the kernels repo.
+  admin crm signals [--status new] [--intent qualified] [--source rb2b] [--account <id>]
+          | record --title "…" [--source bookface] [--kind other] [--intent qualified]
+                   [--name …] [--email …] [--company …] [--domain …] [--linkedin …] [--detail …]
+          | signal <id> qualify|dismiss|link [--account <id>]
+          | accounts [--stage lead] [--q acme] | account <id> | score <account-id>
+                                                       The staff CRM's pipeline: the inbound signal
+                                                       feed, recording a signal with no webhook
+                                                       (Bookface, a tweet like), qualifying or
+                                                       dismissing one, and the explained score.
+                                                       Needs crm:read (reads) / crm:write (writes).
   admin tuning-context [--q "<question>"]              The experiment agent's context pack (JSON):
                                                        the pipeline as deployed, levers, measures,
                                                        goals, related history.

package/lib/commands/admin.mjs

@@ -7,6 +7,7 @@
 //   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)
+//   admin crm signals|record|signal|accounts|account|score …                        (crm:read / crm:write)
 //   admin create-org --domain acme.com [--name "Acme"] [--test] [--no-key] [--key-name N]
 //                    [--capabilities a,b] [--onboard] [--about "…"] [--sitemap <url>]
 //                    [--cms <provider>] [--posts N] [--seers suggest|skip] [--no-visuals]
@@ -410,14 +411,118 @@ async function cmdAdminTuningContext(ctx) {
 	);
 }
 
+/* ------------------------------------------------------------ the staff CRM */
+
+const CRM = "/api/superadmin/crm";
+
+function signalLine(s) {
+	const who = [s.personName, s.companyName ?? s.companyDomain].filter(Boolean).join(" · ");
+	return `${s.id}  [${s.status} · ${s.intent}]  ${s.occurredAt.slice(0, 10)}  ${s.source}/${s.kind}  ${s.title}${who ? `\n    ${who}` : ""}`;
+}
+
+function accountLine(a) {
+	const score = a.likelihood == null ? "—" : a.likelihood.toFixed(2);
+	return `${a.id}  [${a.stage}]  ${score}  ${a.name}${a.domain ? ` (${a.domain})` : ""}${a.isYc ? " · YC" : ""}`;
+}
+
+/**
+ * `admin crm …` — the headless half of the staff CRM, so a background agent can watch the
+ * pipeline and record the signals that have no webhook (Bookface, tweet likes, DMs).
+ * Reads need `crm:read` on the staff key, writes `crm:write`. Every write goes through the
+ * same ingestSignal / actOnSignal the webhooks and the app use.
+ */
+async function cmdAdminCrm(ctx) {
+	const [sub, id, action] = ctx.positionals;
+	const { flags, io } = ctx;
+	const json = flagBool(flags.json);
+	const out = (result, line) => (json ? printResult(io, flags, result) : io.log(line(result)));
+	switch (sub) {
+		case "signals": {
+			const params = new URLSearchParams(
+				compact({
+					status: flagStr(flags.status),
+					intent: flagStr(flags.intent),
+					source: flagStr(flags.source),
+					account_id: flagStr(flags.account),
+					limit: flagStr(flags.limit),
+				})
+			);
+			return out(await staffRequest(ctx, "GET", `${CRM}/signals?${params}`), (r) =>
+				r.signals.length ? r.signals.map(signalLine).join("\n") : "(no signals)"
+			);
+		}
+		case "record": {
+			const body = compact({
+				source: flagStr(flags.source) ?? "agent",
+				kind: flagStr(flags.kind) ?? "other",
+				intent: flagStr(flags.intent),
+				title: flagStr(flags.title),
+				person_name: flagStr(flags.name),
+				person_email: flagStr(flags.email),
+				person_title: flagStr(flags["person-title"]),
+				linkedin_url: flagStr(flags.linkedin),
+				company_name: flagStr(flags.company),
+				company_domain: flagStr(flags.domain),
+				detail: flagStr(flags.detail),
+				url: flagStr(flags.link),
+				external_id: flagStr(flags["external-id"]),
+				occurred_at: flagStr(flags.at),
+				account_id: flagStr(flags.account),
+			});
+			if (!body.title)
+				throw new CliError(
+					'Usage: admin crm record --title "Liked our launch tweet" [--source twitter] [--kind social_engagement] …'
+				);
+			const r = await staffPost(ctx, `${CRM}/signals`, body);
+			return out(r, (x) => `${x.duplicate ? "already recorded" : "recorded"}: ${signalLine(x.signal)}`);
+		}
+		case "signal": {
+			if (!id || !["qualify", "dismiss", "link"].includes(action)) {
+				throw new CliError("Usage: admin crm signal <id> qualify|dismiss|link [--account <account-id>]");
+			}
+			const r = await staffRequest(
+				ctx,
+				"PATCH",
+				`${CRM}/signals/${id}`,
+				compact({ action, account_id: flagStr(flags.account) })
+			);
+			return out(r, (x) => signalLine(x.signal));
+		}
+		case "accounts": {
+			const params = new URLSearchParams(compact({ stage: flagStr(flags.stage), q: flagStr(flags.q) }));
+			return out(await staffRequest(ctx, "GET", `${CRM}/accounts?${params}`), (r) =>
+				r.accounts.length ? r.accounts.map(accountLine).join("\n") : "(no accounts)"
+			);
+		}
+		case "account":
+			if (!id) throw new CliError("Usage: admin crm account <id>");
+			return printResult(io, { ...flags, json: true }, await staffRequest(ctx, "GET", `${CRM}/accounts/${id}`));
+		case "score": {
+			if (!id) throw new CliError("Usage: admin crm score <account-id>");
+			const r = await staffPost(ctx, `${CRM}/accounts/${id}/score`, {});
+			return out(r, (x) =>
+				[
+					accountLine(x.account),
+					...(x.account.scoreFactors ?? []).map(
+						(f) => `  ${f.direction === "risk" ? "−" : "+"}${f.weight.toFixed(2)}  ${f.label}`
+					),
+				].join("\n")
+			);
+		}
+		default:
+			throw new CliError("Usage: admin crm signals|record|signal|accounts|account|score … (see --help)");
+	}
+}
+
 export async function cmdAdmin(ctx) {
 	const sub = ctx.positionals[0];
+	if (sub === "crm") return cmdAdminCrm({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "create-org") return cmdAdminCreateOrg({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "ask") return cmdAdminAsk({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "experiments") return cmdAdminExperiments({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "tuning-context") return cmdAdminTuningContext({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "tuning-import") return cmdAdminTuningImport({ ...ctx, positionals: ctx.positionals.slice(1) });
 	throw new CliError(
-		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin experiments … | admin tuning-context (see --help)'
+		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin experiments … | admin crm … | admin tuning-context (see --help)'
 	);
 }

package/package.json

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