@series-a/cli 0.2.1 → 0.6.2

package/src/commands/insights.mjs

@@ -0,0 +1,1034 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { call } from "../api.mjs";
+import { emit, fail, ctxFrom, withCommonOpts, table, truncate } from "../ui.mjs";
+
+const n = (v) => (v == null ? "" : String(v));
+
+function findGroup(program, name) {
+  return program.commands.find((c) => c.name() === name);
+}
+
+function toCsv(rows) {
+  if (!rows.length) return "";
+  const headers = Array.from(
+    rows.reduce((set, r) => {
+      Object.keys(r).forEach((k) => set.add(k));
+      return set;
+    }, new Set()),
+  );
+  const esc = (v) => {
+    if (v == null) return "";
+    const s = typeof v === "object" ? JSON.stringify(v) : String(v);
+    return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+  };
+  return [
+    headers.join(","),
+    ...rows.map((r) => headers.map((h) => esc(r[h])).join(",")),
+  ].join("\n") + "\n";
+}
+
+/** Campaign analytics subcommands, attached to the existing `campaigns` group. */
+export function registerCampaignAnalytics(program) {
+  const c = findGroup(program, "campaigns");
+  if (!c) return;
+
+  withCommonOpts(c.command("stats <id>"))
+    .description("Campaign funnel: invites, accepts, messages, replies, meetings")
+    .option("--days <n>", "look-back window in days", "30")
+    .action(async function (id) {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("campaigns", "stats", { id, days: Number(o.days) }, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(
+            `\n${d.campaign?.name ?? id}  (${d.campaign?.status ?? "?"}) — last ${o.days}d\n\n`,
+          );
+          process.stdout.write(table(
+            ["metric", "value"],
+            [
+              ["Leads enrolled", d.funnel.leads_enrolled],
+              ["Invites sent", d.funnel.invites_sent],
+              ["Accepted", `${d.funnel.accepts} (${d.rates.accept_rate}%)`],
+              ["Messages sent", d.funnel.messages_sent],
+              ["Replies", `${d.funnel.replies} (${d.rates.reply_rate}%)`],
+              ["Positive replies", `${d.funnel.positive_replies} (${d.rates.positive_rate}%)`],
+              ["Meetings booked", `${d.funnel.meetings_booked} (${d.rates.meeting_rate}%)`],
+              ["Failures", d.funnel.failures],
+            ],
+          ) + "\n");
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(c.command("events <id>"))
+    .description("Campaign event log")
+    .option("--type <t>", "filter by event_type")
+    .option("--since <iso>", "only events after this timestamp")
+    .option("--limit <n>", "max rows", "100")
+    .action(async function (id) {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call(
+          "campaigns", "events",
+          { id, type: o.type, since: o.since, limit: Number(o.limit) },
+          ctxFrom(this),
+        );
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["when", "event", "step", "lead", "sender"],
+            (d.events || []).map((e) => [
+              n(e.created_at).replace("T", " ").slice(0, 19),
+              e.event_type, n(e.step_order), truncate(e.lead_id, 8), truncate(e.sender_account, 14),
+            ]),
+          ) + `\n${d.events?.length ?? 0} rows\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(c.command("health <id>"))
+    .description("Execution health: run state, stalls, retries, watchdog findings")
+    .action(async function (id) {
+      try {
+        const r = await call("campaigns", "health", { id }, ctxFrom(this));
+        emit(this, r, (d) => {
+          const h = d.health;
+          process.stdout.write(
+            h
+              ? `\nStatus: ${h.health_status}  ${h.reason ? `(${h.reason})` : ""}\n` +
+                `Last progress: ${n(h.last_progress_at) || "never"}\n` +
+                `Next attempt:  ${n(h.next_attempt_at) || "—"}\n` +
+                `Retries: ${h.retry_count ?? 0}${h.last_error ? `\nLast error: ${h.last_error}` : ""}\n\n`
+              : "\nNo health record yet.\n\n",
+          );
+          process.stdout.write(table(
+            ["run", "status", "step", "pause reason", "fails", "next attempt"],
+            (d.runs || []).map((r2) => [
+              truncate(r2.id, 8), r2.status, `${r2.current_step ?? 0}/${r2.total_steps ?? 0}`,
+              truncate(r2.pause_reason, 24), r2.consecutive_failure_count ?? 0,
+              n(r2.next_attempt_at).replace("T", " ").slice(0, 19),
+            ]),
+          ) + "\n");
+          if (d.watchdog_findings?.length) {
+            process.stdout.write("\nWatchdog findings:\n" + table(
+              ["severity", "title", "seen", "resolved"],
+              d.watchdog_findings.map((f) => [
+                f.severity, truncate(f.title, 40), f.occurrences,
+                f.resolved_at ? "yes" : "no",
+              ]),
+            ) + "\n");
+          }
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(c.command("leads <id>"))
+    .description("Leads enrolled in a campaign with their current state")
+    .option("--status <s>", "filter by enrolment status")
+    .option("--limit <n>", "max rows", "100")
+    .action(async function (id) {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call(
+          "campaigns", "leads",
+          { id, status: o.status, limit: Number(o.limit) },
+          ctxFrom(this),
+        );
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["lead", "name", "company", "enrolment", "conversation"],
+            (d.leads || []).map((l) => [
+              truncate(l.lead_id, 8), truncate(l.lead?.name, 24), truncate(l.lead?.company, 22),
+              l.status, n(l.lead?.conversation_stage),
+            ]),
+          ) + `\n${d.leads?.length ?? 0} rows\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+}
+
+export function registerAnalytics(program) {
+  const a = program.command("analytics").description("Workspace and campaign analytics");
+
+  withCommonOpts(a.command("overview"))
+    .description("Outreach, content and pipeline results for the workspace")
+    .option("--days <n>", "look-back window", "30")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("analytics", "overview", { days: Number(o.days) }, ctxFrom(this));
+        emit(this, r, (d) => {
+          const m = d.outreach;
+          process.stdout.write(`\nLast ${d.period_days} days\n\n`);
+          process.stdout.write(table(["outreach", "value"], [
+            ["Touches", m.touches], ["Invites sent", m.invites_sent],
+            ["Accepts", `${m.accepts} (${m.rates.accept_rate}%)`],
+            ["Messages sent", m.messages_sent],
+            ["Replies", `${m.replies} (${m.rates.reply_rate}%)`],
+            ["Positive replies", `${m.positive_replies} (${m.rates.positive_rate}%)`],
+            ["Meetings booked", m.meetings_booked], ["Meetings held", m.meetings_held],
+          ]) + "\n");
+          process.stdout.write(table(["content", "value"], [
+            ["Posts distributed", d.content.posts_distributed],
+            ["Impressions", d.content.impressions],
+            ["Engagement", `${d.content.engagement} (${d.content.engagement_rate}%)`],
+            ["Link clicks", d.content.link_clicks],
+          ]) + "\n");
+          process.stdout.write(table(["pipeline", "value"], [
+            ["Opportunities created", d.pipeline.opportunities_created],
+            ["Pipeline value", d.pipeline.pipeline_value],
+            ["Closed won", `${d.pipeline.closed_won_count} / ${d.pipeline.closed_won_value}`],
+          ]) + "\n");
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(a.command("campaigns"))
+    .description("Compare every campaign on the same funnel")
+    .option("--days <n>", "look-back window", "30")
+    .option("--limit <n>", "max campaigns", "25")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call(
+          "analytics", "campaigns",
+          { days: Number(o.days), limit: Number(o.limit) },
+          ctxFrom(this),
+        );
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["campaign", "status", "leads", "invites", "accepts", "msgs", "replies", "pos", "mtgs"],
+            (d.campaigns || []).map((c) => [
+              truncate(c.name, 26), c.status, n(c.leads_enrolled), n(c.invites_sent),
+              n(c.accepts), n(c.messages_sent), n(c.replies), n(c.positive_replies),
+              n(c.meetings_booked),
+            ]),
+          ) + "\n");
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(a.command("content"))
+    .description("Per-post performance: impressions, engagement, clicks")
+    .option("--days <n>", "look-back window", "30")
+    .option("--limit <n>", "max rows", "50")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call(
+          "analytics", "content",
+          { days: Number(o.days), limit: Number(o.limit) },
+          ctxFrom(this),
+        );
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["title", "platform", "impressions", "eng", "eng %", "clicks"],
+            (d.posts || []).map((p) => [
+              truncate(p.title, 34), p.platform, n(p.impressions), n(p.engagement),
+              n(p.engagement_rate), n(p.reference_clicks),
+            ]),
+          ) + `\n${d.posts?.length ?? 0} rows\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(a.command("report"))
+    .description("Full branded performance report (summary, funnel, content, pipeline)")
+    .option("--days <n>", "look-back window", "30")
+    .option("--format <fmt>", "md | json", "md")
+    .option("--out <file>", "write the report to a file instead of stdout")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("analytics", "report", { days: Number(o.days) }, ctxFrom(this));
+        if (o.json && !o.out) return emit(this, r, () => {});
+        const body = o.format === "json"
+          ? JSON.stringify(r, null, 2)
+          : reportMarkdown(r);
+        if (o.out) {
+          await writeFile(o.out, body, "utf8");
+          process.stdout.write(`✔ Wrote report to ${o.out}\n`);
+        } else {
+          process.stdout.write(body + "\n");
+        }
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(a.command("export"))
+    .description("Export workspace analytics as CSV or JSON (overview | campaigns | content | leads | pipeline)")
+    .option("--dataset <name>", "overview | campaigns | content | leads | pipeline", "overview")
+    .option("--format <fmt>", "csv | json", "csv")
+    .option("--days <n>", "look-back window", "30")
+    .option("--limit <n>", "max rows for row-level datasets")
+    .option("--out <file>", "write to a file instead of stdout")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("analytics", "export", {
+          dataset: o.dataset,
+          format: o.format,
+          days: Number(o.days),
+          ...(o.limit ? { limit: Number(o.limit) } : {}),
+        }, ctxFrom(this));
+        const out = o.out === true ? r.filename : o.out;
+        if (out) {
+          await writeFile(out, r.content ?? "", "utf8");
+          process.stdout.write(`✔ Wrote ${r.row_count} ${r.dataset} row(s) to ${out}\n`);
+        } else {
+          process.stdout.write((r.content ?? "") + "\n");
+        }
+      } catch (e) { fail(e); }
+    });
+}
+
+
+function reportMarkdown(d) {
+  const m = d.outreach ?? {};
+  const c = d.content ?? {};
+  const p = d.pipeline ?? {};
+  const rows = (hdrs, data) => [
+    `| ${hdrs.join(" | ")} |`,
+    `| ${hdrs.map(() => "---").join(" | ")} |`,
+    ...data.map((r) => `| ${r.map((v) => n(v)).join(" | ")} |`),
+  ].join("\n");
+
+  return [
+    `# AdvisorPro — Performance Report`,
+    ``,
+    `**Workspace:** ${d.workspace?.name ?? d.workspace?.id}  `,
+    `**Period:** last ${d.period_days} days (since ${n(d.since).slice(0, 10)})  `,
+    `**Generated:** ${n(d.generated_at).slice(0, 16).replace("T", " ")} UTC`,
+    ``,
+    `## Performance summary`,
+    ``,
+    ...(d.summary ?? []).map((s) => `- ${s}`),
+    ``,
+    `## Outreach`,
+    ``,
+    rows(["Metric", "Value"], [
+      ["Touches", m.touches], ["Invites sent", m.invites_sent],
+      ["Accepts", `${n(m.accepts)} (${n(m.rates?.accept_rate)}%)`],
+      ["Messages sent", m.messages_sent],
+      ["Replies", `${n(m.replies)} (${n(m.rates?.reply_rate)}%)`],
+      ["Positive replies", `${n(m.positive_replies)} (${n(m.rates?.positive_rate)}%)`],
+      ["Meetings booked", m.meetings_booked], ["Meetings held", m.meetings_held],
+    ]),
+    ``,
+    `## Campaigns`,
+    ``,
+    rows(["Campaign", "Status", "Leads", "Invites", "Accepts", "Messages", "Replies", "Positive", "Meetings"],
+      (d.campaigns ?? []).map((x) => [
+        x.name, x.status, x.leads_enrolled, x.invites_sent, x.accepts,
+        x.messages_sent, x.replies, x.positive_replies, x.meetings_booked,
+      ])),
+    ``,
+    `## Content`,
+    ``,
+    rows(["Metric", "Value"], [
+      ["Posts distributed", c.posts_distributed], ["Impressions", c.impressions],
+      ["Engagement", `${n(c.engagement)} (${n(c.engagement_rate)}%)`],
+      ["Link clicks", c.link_clicks],
+    ]),
+    ``,
+    rows(["Top posts", "Platform", "Impressions", "Engagement", "Clicks"],
+      (d.top_content ?? []).map((x) => [
+        x.title ?? x.content_item_id, x.platform, x.impressions, x.engagement, x.reference_clicks,
+      ])),
+    ``,
+    `## Revenue impact`,
+    ``,
+    rows(["Metric", "Value"], [
+      ["Opportunities created", p.opportunities_created],
+      ["Pipeline value", p.pipeline_value],
+      ["Closed won", `${n(p.closed_won_count)} / ${n(p.closed_won_value)}`],
+    ]),
+    ``,
+    `---`,
+    `Generated by AdvisorPro CLI.`,
+  ].join("\n");
+}
+
+
+export function registerSafety(program) {
+  const s = program.command("safety").description("LinkedIn safety guardrails (read-only)");
+
+  withCommonOpts(s.command("limits"))
+    .description("Per-seat caps, usage and headroom")
+    .action(async function () {
+      try {
+        const r = await call("safety", "limits", {}, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(`\nGovernor: ${d.governor} · resets ${d.resets_at}\n\n`);
+          process.stdout.write(table(
+            ["account", "cooldown", "invites today", "messages today", "resume at"],
+            (d.seats || []).map((x) => [
+              truncate(x.account_name || x.account_id, 26),
+              x.cooldown_active ? (x.cooldown_reason || "yes") : "clear",
+              x.sent_today.invites, x.sent_today.messages, n(x.resume_at),
+            ]),
+          ) + "\n");
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("reads"))
+    .description("Read budgets and the safe bulk-import size")
+    .option("--account <id>", "include a specific LinkedIn account")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("safety", "reads", { account_id: o.account }, ctxFrom(this));
+        emit(this, r, (d) => {
+          const b = d.budgets;
+          const rows = [
+            ["Workspace daily", b.workspace_daily.used, b.workspace_daily.limit, b.workspace_daily.remaining],
+            ["Workspace bulk", b.workspace_bulk.used, b.workspace_bulk.limit, b.workspace_bulk.remaining],
+            ["Shared pool (bulk)", b.shared_pool.used, b.shared_pool.limit, b.shared_pool.bulk_remaining],
+          ];
+          if (b.account) {
+            rows.push(["Account reads", b.account.reads.used, b.account.reads.limit, b.account.reads.remaining]);
+            rows.push(["Account bulk", b.account.bulk.used, b.account.bulk.limit, b.account.bulk.remaining]);
+          }
+          process.stdout.write(table(["budget", "used", "limit", "remaining"], rows) + "\n");
+          process.stdout.write(`\nSafe bulk import size right now: ${d.safe_bulk_import_size} leads\nResets ${d.resets_at}\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("seats"))
+    .description("Connected LinkedIn seats and their health")
+    .action(async function () {
+      try {
+        const r = await call("safety", "seats", {}, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["account", "id", "cooldown", "reason", "resume at", "strikes"],
+            (d.seats || []).map((x) => [
+              truncate(x.account_name, 22), truncate(x.account_id, 12),
+              x.cooldown_active ? "active" : "clear", truncate(x.cooldown_reason, 22),
+              n(x.resume_at), n(x.backoff?.strikes),
+            ]),
+          ) + "\n");
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("cooldowns"))
+    .description("Active cooldowns and holds")
+    .action(async function () {
+      try {
+        const r = await call("safety", "cooldowns", {}, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["account", "source", "class", "reason", "clears at"],
+            (d.active || []).map((x) => [
+              truncate(x.account_name || x.account_id, 24), x.source, n(x.class),
+              truncate(x.reason, 30), n(x.resume_at),
+            ]),
+          ) + `\n${d.active?.length ?? 0} active\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("check"))
+    .description("Preflight a LinkedIn action against current guardrails")
+    .requiredOption("--account <id>", "LinkedIn account id")
+    .option("--action <name>", "action name", "sendMessage")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call(
+          "safety", "check",
+          { account_id: o.account, action_name: o.action },
+          ctxFrom(this),
+        );
+        emit(this, r, (d) => {
+          process.stdout.write(
+            `\n${d.allowed ? "ALLOWED" : "BLOCKED"} — ${d.action} on ${d.account_id}\n` +
+            (d.allowed ? "" : `Reason: ${d.blocked_reason}\nRetry at: ${n(d.retry_at)}\n`) +
+            `\n${d.note}\n`,
+          );
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("policy"))
+    .description("Governor policy and enforcement mode")
+    .action(async function () {
+      try {
+        const r = await call("safety", "policy", {}, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(JSON.stringify(d, null, 2) + "\n"));
+      } catch (e) { fail(e); }
+    });
+}
+
+export function registerCtas(program) {
+  const c = program.command("ctas").description("Knowledge-base CTAs used in content and sequences");
+
+  withCommonOpts(c.command("list"))
+    .description("List CTAs")
+    .option("--all", "include inactive")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("ctas", "list", { active_only: !o.all }, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["id", "label", "url", "type", "primary", "active"],
+            (d.ctas || []).map((x) => [
+              truncate(x.id, 8), truncate(x.label, 26), truncate(x.url, 40),
+              n(x.type), x.is_primary ? "yes" : "", x.is_active ? "yes" : "no",
+            ]),
+          ) + `\n${d.ctas?.length ?? 0} rows\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(c.command("create"))
+    .description("Create a CTA")
+    .requiredOption("--label <text>", "button/link label")
+    .requiredOption("--url <url>", "destination URL")
+    .option("--type <t>", "cta type", "link")
+    .option("--primary", "mark as primary CTA")
+    .option("--sort <n>", "sort order", "0")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("ctas", "create", {
+          label: o.label, url: o.url, type: o.type,
+          is_primary: !!o.primary, sort_order: Number(o.sort),
+        }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✔ CTA created: ${d.cta?.id}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(c.command("update <id>"))
+    .description("Update a CTA")
+    .option("--label <text>", "label")
+    .option("--url <url>", "url")
+    .option("--type <t>", "type")
+    .option("--sort <n>", "sort order")
+    .option("--primary <bool>", "primary flag (true/false)")
+    .action(async function (id) {
+      try {
+        const o = this.optsWithGlobals();
+        const patch = { id };
+        if (o.label) patch.label = o.label;
+        if (o.url) patch.url = o.url;
+        if (o.type) patch.type = o.type;
+        if (o.sort !== undefined) patch.sort_order = Number(o.sort);
+        if (o.primary !== undefined) patch.is_primary = o.primary === "true";
+        const r = await call("ctas", "update", patch, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✔ CTA updated: ${d.cta?.id}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(c.command("deactivate <id>"))
+    .description("Deactivate a CTA")
+    .action(async function (id) {
+      try {
+        const r = await call("ctas", "deactivate", { id }, ctxFrom(this));
+        emit(this, r, () => process.stdout.write(`✔ CTA deactivated: ${id}\n`));
+      } catch (e) { fail(e); }
+    });
+}
+
+export function registerNotifications(program) {
+  const nCmd = program.command("notifications").description("Workspace notifications");
+
+  withCommonOpts(nCmd.command("list"))
+    .description("List notifications")
+    .option("--unread", "unread only")
+    .option("--type <t>", "filter by type")
+    .option("--limit <n>", "max rows", "50")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call(
+          "notifications", "list",
+          { unread_only: !!o.unread, type: o.type, limit: Number(o.limit) },
+          ctxFrom(this),
+        );
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["when", "type", "title", "read"],
+            (d.notifications || []).map((x) => [
+              n(x.created_at).replace("T", " ").slice(0, 16), truncate(x.type, 22),
+              truncate(x.title, 42), x.is_read ? "yes" : "no",
+            ]),
+          ) + `\n${d.notifications?.length ?? 0} rows\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(nCmd.command("read <ids...>"))
+    .description("Mark notifications as read")
+    .action(async function (ids) {
+      try {
+        const r = await call("notifications", "mark_read", { ids }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✔ ${d.updated} marked read\n`));
+      } catch (e) { fail(e); }
+    });
+}
+
+export function registerAudiences(program) {
+  const a = program.command("audiences").description("Smart audiences / lead segments");
+
+  withCommonOpts(a.command("list"))
+    .description("List audiences")
+    .action(async function () {
+      try {
+        const r = await call("audiences", "list", {}, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["id", "name", "type", "leads", "updated"],
+            (d.audiences || []).map((x) => [
+              truncate(x.id, 8), truncate(x.name, 30), n(x.segment_type),
+              n(x.lead_count), n(x.updated_at).slice(0, 10),
+            ]),
+          ) + `\n${d.audiences?.length ?? 0} rows\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(a.command("members <id>"))
+    .description("List the leads in an audience")
+    .option("--limit <n>", "max rows", "100")
+    .action(async function (id) {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("audiences", "members", { id, limit: Number(o.limit) }, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["id", "name", "title", "company"],
+            (d.leads || []).map((l) => [
+              truncate(l.id, 8), truncate(l.name, 24), truncate(l.title, 26), truncate(l.company, 22),
+            ]),
+          ) + `\n${d.count} members\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(a.command("add-to-campaign <id> <campaignId>"))
+    .description("Enrol every lead in an audience into a campaign")
+    .action(async function (id, campaignId) {
+      try {
+        const r = await call("audiences", "add_to_campaign", { id, campaign_id: campaignId }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✔ Added ${d.added} of ${d.candidates} leads\n`));
+      } catch (e) { fail(e); }
+    });
+}
+
+export function registerNewsletter(program) {
+  const nl = program.command("newsletter").description("Newsletters, audiences and contacts");
+
+  withCommonOpts(nl.command("list"))
+    .description("List newsletters")
+    .option("--limit <n>", "max rows", "50")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("newsletter", "list", { limit: Number(o.limit) }, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["id", "title", "status", "scheduled", "published"],
+            (d.newsletters || []).map((x) => [
+              truncate(x.id, 8), truncate(x.title, 36), x.status,
+              n(x.scheduled_date).slice(0, 16), n(x.published_at).slice(0, 10),
+            ]),
+          ) + `\n${d.newsletters?.length ?? 0} rows\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(nl.command("show <id>"))
+    .description("Show one newsletter")
+    .action(async function (id) {
+      try {
+        const r = await call("newsletter", "get", { id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(JSON.stringify(d.newsletter, null, 2) + "\n"));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(nl.command("create"))
+    .description("Create a newsletter draft")
+    .requiredOption("--subject <s>", "email subject")
+    .option("--preview <s>", "preview text")
+    .option("--body <html>", "HTML body")
+    .option("--file <path>", "read the HTML body from a file")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const body = o.file ? await readFile(o.file, "utf8") : (o.body ?? "");
+        const r = await call("newsletter", "create", {
+          subject: o.subject, preview_text: o.preview, body,
+        }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✔ Created draft ${d.newsletter?.id}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(nl.command("edit <id>"))
+    .description("Update a newsletter draft")
+    .option("--subject <s>").option("--preview <s>").option("--body <html>")
+    .option("--file <path>", "read the HTML body from a file")
+    .option("--status <s>", "draft | scheduled")
+    .action(async function (id) {
+      try {
+        const o = this.optsWithGlobals();
+        const params = { id };
+        if (o.subject !== undefined) params.subject = o.subject;
+        if (o.preview !== undefined) params.preview_text = o.preview;
+        if (o.status !== undefined) params.status = o.status;
+        if (o.file) params.body = await readFile(o.file, "utf8");
+        else if (o.body !== undefined) params.body = o.body;
+        const r = await call("newsletter", "update", params, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✔ Updated ${d.newsletter?.id ?? id}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(nl.command("delete <id>"))
+    .description("Delete a newsletter draft")
+    .action(async function (id) {
+      try {
+        const r = await call("newsletter", "delete", { id }, ctxFrom(this));
+        emit(this, r, () => process.stdout.write(`✔ Deleted ${id}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(nl.command("schedule <id> <isoTimestamp>"))
+    .description("Schedule a newsletter")
+    .action(async function (id, ts) {
+      try {
+        const r = await call("newsletter", "schedule", { id, scheduled_date: ts }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✔ Scheduled for ${d.newsletter?.scheduled_date}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(nl.command("audiences"))
+    .description("List newsletter audiences")
+    .action(async function () {
+      try {
+        const r = await call("newsletter", "audiences", {}, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["id", "name", "description"],
+            (d.audiences || []).map((x) => [truncate(x.id, 8), truncate(x.name, 28), truncate(x.description, 40)]),
+          ) + "\n");
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(nl.command("contacts"))
+    .description("List newsletter contacts")
+    .option("--audience <id>", "filter by audience")
+    .option("--limit <n>", "max rows", "100")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call(
+          "newsletter", "contacts",
+          { audience_id: o.audience, limit: Number(o.limit) },
+          ctxFrom(this),
+        );
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["email", "name", "unsubscribed", "source"],
+            (d.contacts || []).map((x) => [
+              truncate(x.email, 34), truncate(`${n(x.first_name)} ${n(x.last_name)}`.trim(), 24),
+              x.unsubscribed ? "yes" : "", n(x.source),
+            ]),
+          ) + `\n${d.contacts?.length ?? 0} rows\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+}
+
+export function registerVideo(program) {
+  const v = program.command("video").description("Video projects");
+
+  withCommonOpts(v.command("list"))
+    .description("List video projects")
+    .option("--status <s>", "filter by status")
+    .option("--limit <n>", "max rows", "50")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("video", "list", { status: o.status, limit: Number(o.limit) }, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["id", "title", "status", "progress", "published"],
+            (d.videos || []).map((x) => [
+              truncate(x.id, 8), truncate(x.title, 32), x.status,
+              n(x.progress), n(x.published_at).slice(0, 10),
+            ]),
+          ) + `\n${d.videos?.length ?? 0} rows\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("show <id>"))
+    .description("Show a video project and its render status")
+    .action(async function (id) {
+      try {
+        const r = await call("video", "get", { id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(JSON.stringify(d.video, null, 2) + "\n"));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("share <id>"))
+    .description("Get the public share link for a video")
+    .action(async function (id) {
+      try {
+        const r = await call("video", "share", { id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`${d.share_url ?? "not shared"}\n`));
+      } catch (e) { fail(e); }
+    });
+}
+
+export function registerWatchlist(program) {
+  const w = program.command("watchlist").description("Intelligence watchlist (P0–P3 priorities)");
+
+  withCommonOpts(w.command("list"))
+    .description("List watchlist items")
+    .option("--all", "include inactive")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("watchlist", "list", { active_only: !o.all }, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["id", "name", "type", "priority", "matches", "last match"],
+            (d.items || []).map((x) => [
+              truncate(x.id, 8), truncate(x.name, 28), n(x.type), n(x.priority),
+              n(x.match_count), n(x.last_match_at).slice(0, 10),
+            ]),
+          ) + `\n${d.items?.length ?? 0} rows\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(w.command("add"))
+    .description("Add a watchlist item")
+    .requiredOption("--name <name>", "company, person or topic")
+    .option("--type <t>", "company|person|topic|competitor", "company")
+    .option("--priority <p>", "P0|P1|P2|P3", "P2")
+    .option("--keywords <list>", "comma-separated keywords")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("watchlist", "add", {
+          name: o.name, type: o.type, priority: o.priority,
+          keywords: o.keywords ? o.keywords.split(",").map((s) => s.trim()) : [],
+        }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✔ Added: ${d.item?.id}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(w.command("priority <id> <priority>"))
+    .description("Set the priority tier (P0–P3)")
+    .action(async function (id, priority) {
+      try {
+        const r = await call("watchlist", "update", { id, priority }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✔ ${d.item?.name} → ${d.item?.priority}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(w.command("remove <id>"))
+    .description("Remove a watchlist item")
+    .action(async function (id) {
+      try {
+        const r = await call("watchlist", "remove", { id }, ctxFrom(this));
+        emit(this, r, () => process.stdout.write(`✔ Removed ${id}\n`));
+      } catch (e) { fail(e); }
+    });
+}
+
+export function registerMeetings(program) {
+  const m = program.command("meetings").description("Meeting transcripts (anonymised)");
+
+  withCommonOpts(m.command("list"))
+    .description("List transcripts")
+    .option("--limit <n>", "max rows", "50")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("meetings", "list", { limit: Number(o.limit) }, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["id", "name", "when"],
+            (d.meetings || []).map((x) => [
+              truncate(x.id, 8), truncate(x.name, 44), n(x.created_at).slice(0, 10),
+            ]),
+          ) + `\n${d.meetings?.length ?? 0} rows\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(m.command("show <id>"))
+    .description("Show a transcript (redacted unless anonymised)")
+    .action(async function (id) {
+      try {
+        const r = await call("meetings", "get", { id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(JSON.stringify(d.meeting, null, 2) + "\n"));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(m.command("transcripts"))
+    .description("List meeting transcripts from the transcript store")
+    .option("--provider <p>", "filter by provider")
+    .option("--since <iso>", "only meetings on/after this date")
+    .option("--limit <n>", "max rows", "50")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("meetings", "transcripts", {
+          provider: o.provider, since: o.since, limit: Number(o.limit),
+        }, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["id", "title", "provider", "date", "mins", "state"],
+            (d.transcripts || []).map((x) => [
+              truncate(x.id, 8), truncate(x.title, 34), x.provider,
+              n(x.meeting_date).slice(0, 10), String(x.duration_minutes ?? ""),
+              x.anonymised_status ?? "",
+            ]),
+          ) + `\n${d.transcripts?.length ?? 0} rows\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(m.command("transcript <id>"))
+    .description("Show one transcript (redacted unless anonymised)")
+    .action(async function (id) {
+      try {
+        const r = await call("meetings", "transcript", { id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(JSON.stringify(d.transcript, null, 2) + "\n"));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(m.command("sync"))
+    .description("Trigger a provider transcript sync")
+    .action(async function () {
+      try {
+        const r = await call("meetings", "sync", {}, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(d.triggered ? "✔ Sync triggered\n" : "✖ Sync failed\n"));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(m.command("integrations"))
+    .description("List connected meeting providers")
+    .action(async function () {
+      try {
+        const r = await call("meetings", "integrations", {}, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["provider", "active", "last sync"],
+            (d.integrations || []).map((x) => [x.provider, x.is_active ? "yes" : "no", n(x.last_synced_at)]),
+          ) + "\n");
+        });
+      } catch (e) { fail(e); }
+    });
+}
+
+export function registerActivity(program) {
+  withCommonOpts(program.command("activity"))
+    .description("Recent activity across agents, campaigns and content")
+    .option("--days <n>", "look-back window", "7")
+    .option("--limit <n>", "max rows", "50")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("activity", "list", { days: Number(o.days), limit: Number(o.limit) }, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["when", "kind", "type", "source"],
+            (d.activity || []).map((x) => [
+              n(x.at).replace("T", " ").slice(0, 19), x.kind, truncate(x.type, 28), truncate(x.source, 24),
+            ]),
+          ) + `\n${d.activity?.length ?? 0} rows\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+}
+
+export function registerWorkspacesExtras(program) {
+  const w = program.command("workspaces").description("Workspaces (admin keys only)");
+
+  withCommonOpts(w.command("list"))
+    .description("List workspaces this key can reach")
+    .action(async function () {
+      try {
+        const r = await call("workspaces", "list", {}, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["id", "name", "created"],
+            (d.workspaces || []).map((x) => [x.id, truncate(x.name, 34), n(x.created_at).slice(0, 10)]),
+          ) + `\n${d.workspaces?.length ?? 0} rows\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(w.command("members <id>"))
+    .description("List members and roles of a workspace")
+    .action(async function (id) {
+      try {
+        const r = await call("workspaces", "members", { id }, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["user_id", "role", "joined"],
+            (d.members || []).map((x) => [x.user_id, x.role, n(x.created_at).slice(0, 10)]),
+          ) + `\n${d.members?.length ?? 0} members\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+}
+
+export function registerExport(program) {
+  withCommonOpts(program.command("export <resource> <action>"))
+    .description("Run any list action and write the rows to CSV")
+    .option("--out <file>", "output file", "export.csv")
+    .option("--params <json>", "extra params as JSON", "{}")
+    .action(async function (resource, action) {
+      try {
+        const o = this.optsWithGlobals();
+        let params = {};
+        try { params = JSON.parse(o.params); } catch { throw new Error("--params must be valid JSON"); }
+        const r = await call(resource, action, params, ctxFrom(this));
+        const arrayKey = Object.keys(r).find((k) => Array.isArray(r[k]));
+        if (!arrayKey) throw new Error("That action did not return a list of rows");
+        const csv = toCsv(r[arrayKey]);
+        await writeFile(o.out, csv, "utf8");
+        process.stdout.write(`✔ Wrote ${r[arrayKey].length} rows to ${o.out}\n`);
+      } catch (e) { fail(e); }
+    });
+}
+
+
+export function registerIntegrations(program) {
+  const i = program.command("integrations").description("Integration status (read-only)");
+
+  withCommonOpts(i.command("status"))
+    .description("List every configured integration and its state")
+    .action(async function () {
+      try {
+        const r = await call("integrations", "list", {}, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["kind", "platform", "name", "state", "last activity"],
+            (d.integrations || []).map((x) => [
+              x.kind, truncate(x.platform, 20), truncate(x.display_name, 24), x.state,
+              n(x.last_synced_at || x.last_tested_at).slice(0, 16),
+            ]),
+          ) + `\n${d.connected ?? 0}/${d.total ?? 0} connected\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(i.command("check <platform>"))
+    .description("Health-check one integration")
+    .action(async function (platform) {
+      try {
+        const r = await call("integrations", "check", { platform }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(JSON.stringify(d, null, 2) + "\n"));
+      } catch (e) { fail(e); }
+    });
+}