@series-a/cli 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to this package are documented here. This project follows
 [Semantic Versioning](https://semver.org/) and uses
 [Changesets](https://github.com/changesets/changesets) to manage releases.
 
+## 1.4.0 — Company news, brand imagery fix, API reliability
+
+Version jumps from 0.28.0 to 1.4.0 because npm already has releases up to 1.3.2.
+
+- New `advisoros leads company-refresh <ids...>` fetches company details and recent company news for contacts through Brave Search. It only works when the workspace's "Company news" switch is on, each company is refreshed at most once every 14 days, and every lookup is billed as `web_search` credits.
+- `brand set-imagery` works again for workspaces whose owner is stored in the older `ws_…` format. Before, it failed with "One of the supplied ids is not a valid identifier".
+- API reliability: the CLI, MCP and Agent API briefly returned 503 because the server function crashed on startup. That is fixed. No change is needed on the CLI side.
+- Server-side agent fixes also reach CLI-triggered runs: Market Research, News Monitor, Competitive Intel, Social Listening and the Intelligence Synthesizer no longer crash when the AI sends its lists in a different format.
+- Campaigns: "Stop if replied (else continue)" checks only that contact's own saved replies (it never spends a LinkedIn read), and each contact's branches and waits are tracked separately.
+
+## 0.28.0 — Instantly email campaigns
+
+- New `advisoros email` command group (alias `instantly`) drives the workspace's Instantly account through its own connected key — the key never leaves the server.
+  - `email status`, `email actions`, and `email call <action> --data '{…}'` for any supported action.
+  - `email campaigns list|get|create|update|activate|pause|duplicate|delete|sending-status|analytics|steps` — `steps` shows sent, delivered, opened and replied per email.
+  - `email sequence show|set|history|restore|test|branches|branch-pause|branch-resume|branch-delete|variables` — `history` lists every saved version from the app, `restore` puts one back live (the current sequence is saved to history first).
+  - `email accounts list|get|pause|resume|mark-fixed|warmup on/off|limit|test` for sending mailboxes.
+  - `email leads list|add|import (CSV, max 500)|remove|move|status|merge|lists|list-create|list-delete|blocklist|block|unblock`.
+  - `email tags` and `email labels`.
+- Agent API: new `instantly` resource (alias `email`) with snake_case actions plus `status`, `actions`, `sequence_history`, `sequence_restore`.
+- Destructive commands (delete, remove, restore) ask for confirmation; pass `--yes` in scripts.
+- Changes require an Instantly key on the workspace (Integrations → Instantly); without one, commands return a clear "connect Instantly" message.
+
 ## 0.27.0 — Campaign engine reliability
 
 - Campaigns no longer restart from the beginning. Finished runs were being relaunched roughly every minute and began again at step one, so the same people were actioned repeatedly (one lead recorded 875 profile views). Each enrolled lead now keeps one permanent progress record for the lifetime of the campaign.

package/SKILLS.md

@@ -342,3 +342,18 @@ Deletion is allowed but always two-step:
 
 When in doubt: `advisoros <command> --help`, `docs/cli.md`, and
 `docs/agent-api.md` are the canonical references.
+
+## Email campaigns (Instantly)
+
+Needs an Instantly key on the workspace (Integrations → Instantly).
+
+```bash
+advisoros email status
+advisoros email campaigns list
+advisoros email campaigns steps <campaignId>          # sent / delivered / opened / replied per email
+advisoros email sequence history <campaignId>
+advisoros email sequence restore <versionId> --yes    # current sequence is saved to history first
+advisoros email accounts list
+advisoros email leads import <campaignId> leads.csv   # email,first_name,last_name,company_name
+advisoros email call <action> --data '{"id":"..."}'  # any action from `email actions`
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-a/cli",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "AdvisorPro command-line interface — drive leads, campaigns, sequences and agents from your terminal.",
   "type": "module",
   "bin": {

package/src/commands/email.mjs

@@ -0,0 +1,130 @@
+// `advisoros email` — Instantly email campaigns, accounts, leads and sequences.
+import { readFile } from "node:fs/promises";
+import { call } from "../api.mjs";
+import { emit, fail, ctxFrom, withCommonOpts, table, truncate, confirmDestructive } from "../ui.mjs";
+
+const STATUS = { "-99": "suspended", "-2": "account paused", "-1": "archived", 0: "draft", 1: "active", 2: "paused", 3: "completed", 4: "subsequence" };
+const items = (r) => r?.result?.items ?? (Array.isArray(r?.result) ? r.result : []);
+const today = () => new Date().toISOString().slice(0, 10);
+const daysAgo = (n) => { const d = new Date(); d.setDate(d.getDate() - n); return d.toISOString().slice(0, 10); };
+const range = (o) => ({ start_date: o.from || (o.days === "all" ? "2020-01-01" : daysAgo(Number(o.days || 30))), end_date: o.to || today() });
+const parseJson = (s, label) => { try { return JSON.parse(s); } catch { throw new Error(`${label} must be valid JSON`); } };
+
+/** Run one Instantly action and print the result. */
+function run(cmd, action, params, human, destructive) {
+  return async function (...args) {
+    try {
+      const self = this;
+      const p = typeof params === "function" ? params(...args, self.optsWithGlobals()) : params;
+      if (destructive) await confirmDestructive(self, typeof destructive === "function" ? destructive(...args) : destructive);
+      const r = await call("instantly", action, p, ctxFrom(self));
+      emit(self, r, human || ((d) => process.stdout.write(`✓ ${d.action ?? action} done\n`)));
+    } catch (e) { fail(e); }
+  };
+}
+
+export function registerEmail(program) {
+  const email = program.command("email").alias("instantly").description("Instantly email campaigns — campaigns, senders, leads, sequences");
+
+  withCommonOpts(email.command("status")).description("Is an Instantly key connected for this workspace?")
+    .action(run(null, "status", {}, (d) => process.stdout.write(d.configured ? `✓ Instantly connected (${d.key_preview})\n` : "✖ No Instantly key — connect it in Integrations → Instantly\n")));
+  withCommonOpts(email.command("actions")).description("List every supported Instantly action (for `email call`)")
+    .action(run(null, "actions", {}, (d) => process.stdout.write(d.actions.join("\n") + "\n")));
+  withCommonOpts(email.command("call <action>")).description("Run any supported action with raw JSON data")
+    .option("--data <json>", "JSON payload", "{}")
+    .action(run(null, "call", (action, o) => ({ op: action, data: parseJson(o.data, "--data") }), (d) => process.stdout.write(JSON.stringify(d.result, null, 2) + "\n")));
+
+  // ── Campaigns ──
+  const c = email.command("campaigns").description("Email campaigns");
+  withCommonOpts(c.command("list")).option("--search <q>").option("--status <n>", "0 draft · 1 active · 2 paused · 3 completed").option("--limit <n>", "", "50")
+    .action(run(null, "list_campaigns", (o) => ({ search: o.search, status: o.status, limit: Number(o.limit) }), (d) =>
+      process.stdout.write(table(["id", "name", "status", "daily limit", "senders"], items(d).map((x) => [x.id, truncate(x.name, 44), STATUS[x.status] ?? x.status, x.daily_limit ?? "—", (x.email_list || []).length])))));
+  withCommonOpts(c.command("get <id>")).action(run(null, "get_campaign", (id) => ({ id }), (d) => process.stdout.write(JSON.stringify(d.result, null, 2) + "\n")));
+  withCommonOpts(c.command("create <name>")).option("--daily-limit <n>").option("--senders <emails>", "comma-separated sending accounts")
+    .action(run(null, "create_campaign", (name, o) => ({ name, daily_limit: o.dailyLimit ? Number(o.dailyLimit) : undefined, email_list: o.senders?.split(",").map((s) => s.trim()).filter(Boolean),
+      campaign_schedule: { schedules: [{ name: "Default", timing: { from: "09:00", to: "17:00" }, days: { 1: true, 2: true, 3: true, 4: true, 5: true }, timezone: "America/Chicago" }] } }),
+      (d) => process.stdout.write(`✓ Created ${d.result?.id}\n`)));
+  withCommonOpts(c.command("update <id>")).option("--data <json>", "fields to change (name, daily_limit, email_list, stop_on_reply, …)", "{}")
+    .action(run(null, "update_campaign", (id, o) => ({ id, ...parseJson(o.data, "--data") })));
+  withCommonOpts(c.command("activate <id>")).action(run(null, "activate_campaign", (id) => ({ id })));
+  withCommonOpts(c.command("pause <id>")).action(run(null, "pause_campaign", (id) => ({ id })));
+  withCommonOpts(c.command("duplicate <id>")).action(run(null, "duplicate_campaign", (id) => ({ id }), (d) => process.stdout.write(`✓ Duplicated → ${d.result?.id ?? "new campaign"}\n`)));
+  withCommonOpts(c.command("delete <id>")).option("-y, --yes", "skip confirmation")
+    .action(run(null, "delete_campaign", (id) => ({ id }), undefined, (id) => `Delete email campaign ${id} in Instantly. This cannot be undone.`));
+  withCommonOpts(c.command("sending-status <id>")).action(run(null, "sending_status", (id) => ({ id }), (d) => process.stdout.write(JSON.stringify(d.result, null, 2) + "\n")));
+  withCommonOpts(c.command("analytics <id>")).option("--days <n>", "7 | 30 | 90 | all", "30").option("--from <date>").option("--to <date>")
+    .action(run(null, "analytics", (id, o) => ({ id, ...range(o) }), (d) => { const a = Array.isArray(d.result) ? d.result[0] : d.result; process.stdout.write(table(["metric", "value"], ["leads_count", "contacted_count", "emails_sent_count", "open_count_unique", "link_click_count_unique", "reply_count_unique", "bounced_count", "unsubscribed_count", "total_interested", "total_meeting_booked", "total_opportunity_value"].map((k) => [k, a?.[k] ?? 0]))); }));
+  withCommonOpts(c.command("steps <id>")).description("Per-email results: sent, delivered, opened, replied").option("--days <n>", "", "all")
+    .action(run(null, "step_analytics", (id, o) => ({ campaign_id: id, ...range(o) }), (d) => {
+      const rows = Array.isArray(d.result) ? d.result : items(d);
+      process.stdout.write(table(["step", "variant", "sent", "delivered", "opened", "replied"], rows.map((r) => [Number(r.step ?? 0) + 1, r.variant ?? "—", r.sent ?? 0, Math.max(0, (r.sent ?? 0) - (r.bounced ?? 0)), r.unique_opened ?? r.opened ?? 0, r.unique_replies ?? r.replies ?? 0])));
+    }));
+
+  // ── Sequence ──
+  const s = email.command("sequence").description("Email steps, test sends, history and restore");
+  withCommonOpts(s.command("show <campaignId>")).action(run(null, "get_campaign", (id) => ({ id }), (d) => {
+    const steps = d.result?.sequences?.[0]?.steps ?? [];
+    process.stdout.write(table(["#", "wait", "subject", "variants"], steps.map((st, i) => [i + 1, `${st.delay ?? 0} ${st.delay_unit || "days"}`, truncate(st.variants?.[0]?.subject || "", 50), (st.variants || []).length])));
+  }));
+  withCommonOpts(s.command("set <campaignId> <file>")).description("Replace the sequence from a JSON file: [{delay, delay_unit, variants:[{subject, body}]}]")
+    .action(async function (id, file) { try { const steps = parseJson(await readFile(file, "utf8"), file); const r = await call("instantly", "update_campaign", { id, sequences: [{ steps: steps.map((st) => ({ type: "email", ...st })) }] }, ctxFrom(this)); emit(this, r, () => process.stdout.write(`✓ Sequence saved (${steps.length} emails)\n`)); } catch (e) { fail(e); } });
+  withCommonOpts(s.command("history <campaignId>")).option("--limit <n>", "", "20")
+    .action(run(null, "sequence_history", (id, o) => ({ campaign_id: id, limit: Number(o.limit) }), (d) =>
+      process.stdout.write(table(["version", "saved", "note", "emails"], d.versions.map((v) => [v.id, v.created_at.slice(0, 16).replace("T", " "), v.note || "Saved", (v.steps || []).filter((x) => x.type !== "wait").length])))));
+  withCommonOpts(s.command("restore <versionId>")).option("-y, --yes", "skip confirmation")
+    .action(run(null, "sequence_restore", (version_id) => ({ version_id }), (d) => process.stdout.write(`✓ Restored version ${d.version_id} on campaign ${d.campaign_id}\n`), (v) => `Replace the live Instantly sequence with version ${v}. The current sequence is saved to history first.`));
+  withCommonOpts(s.command("test")).requiredOption("--from <email>", "sending account").requiredOption("--to <email>").requiredOption("--subject <s>").requiredOption("--body <b>")
+    .action(run(null, "send_test_email", (o) => ({ eaccount: o.from, to_address_email_list: o.to, subject: o.subject, body: o.body })));
+  withCommonOpts(s.command("branches <campaignId>")).description("List follow-up branches (subsequences)")
+    .action(run(null, "list_subsequences", (id) => ({ parent_campaign: id, limit: 100 }), (d) => process.stdout.write(table(["id", "name", "status"], items(d).map((x) => [x.id, x.name, STATUS[x.status] ?? x.status])))));
+  for (const [name, action] of [["branch-pause", "pause_subsequence"], ["branch-resume", "resume_subsequence"]]) withCommonOpts(s.command(`${name} <id>`)).action(run(null, action, (id) => ({ id })));
+  withCommonOpts(s.command("branch-delete <id>")).option("-y, --yes").action(run(null, "delete_subsequence", (id) => ({ id }), undefined, (id) => `Delete follow-up branch ${id}.`));
+  withCommonOpts(s.command("variables <campaignId> <json>")).description("Set campaign variables").action(run(null, "set_variables", (id, j) => ({ id, variables: parseJson(j, "variables") })));
+
+  // ── Sending accounts ──
+  const a = email.command("accounts").description("Sending mailboxes");
+  withCommonOpts(a.command("list")).option("--search <q>").option("--limit <n>", "", "100")
+    .action(run(null, "list_accounts", (o) => ({ search: o.search, limit: Number(o.limit) }), (d) => {
+      const rows = items(d); if (!rows.length) return process.stdout.write("No sending mailboxes in this Instantly workspace.\n");
+      process.stdout.write(table(["email", "status", "daily limit", "warm-up"], rows.map((x) => [x.email, x.status ?? "—", x.daily_limit ?? "—", x.warmup_status ?? "—"])));
+    }));
+  withCommonOpts(a.command("get <email>")).action(run(null, "get_account", (e) => ({ email: e }), (d) => process.stdout.write(JSON.stringify(d.result, null, 2) + "\n")));
+  for (const [name, action] of [["pause", "pause_account"], ["resume", "resume_account"], ["mark-fixed", "mark_account_fixed"]]) withCommonOpts(a.command(`${name} <email>`)).action(run(null, action, (e) => ({ email: e })));
+  withCommonOpts(a.command("warmup <on|off> <emails...>")).action(run(null, "call", (mode, emails) => ({ op: mode === "off" ? "disableWarmup" : "enableWarmup", data: { emails } })));
+  withCommonOpts(a.command("limit <email> <n>")).description("Set a mailbox's daily send limit").action(run(null, "update_account", (e, n) => ({ email: e, daily_limit: Number(n) })));
+  withCommonOpts(a.command("test <emails...>")).description("Run a health (vitals) test").action(run(null, "test_account_vitals", (emails) => ({ accounts: emails }), (d) => process.stdout.write(JSON.stringify(d.result, null, 2) + "\n")));
+
+  // ── Leads ──
+  const l = email.command("leads").description("Campaign leads, lists and block list");
+  withCommonOpts(l.command("list <campaignId>")).option("--search <q>").option("--limit <n>", "", "100")
+    .action(run(null, "list_leads", (id, o) => ({ campaign: id, search: o.search, limit: Number(o.limit) }), (d) =>
+      process.stdout.write(table(["id", "email", "name", "company", "status"], items(d).map((x) => [x.id, x.email, [x.first_name, x.last_name].filter(Boolean).join(" "), truncate(x.company_name || "", 24), x.status ?? "—"])))));
+  withCommonOpts(l.command("add <campaignId> <email>")).option("--first <n>").option("--last <n>").option("--company <c>")
+    .action(run(null, "create_lead", (id, e, o) => ({ campaign: id, email: e, first_name: o.first, last_name: o.last, company_name: o.company, skip_if_in_campaign: true })));
+  withCommonOpts(l.command("import <campaignId> <csv>")).description("Bulk add from CSV (email,first_name,last_name,company_name), max 500")
+    .action(async function (id, file) {
+      try {
+        const lines = (await readFile(file, "utf8")).split(/\r?\n/).map((x) => x.trim()).filter(Boolean);
+        const header = lines[0].toLowerCase().includes("email") ? lines.shift().toLowerCase().split(",").map((x) => x.trim()) : ["email", "first_name", "last_name", "company_name"];
+        const rows = lines.slice(0, 500).map((line) => Object.fromEntries(line.split(",").map((v, i) => [header[i], v.trim()])));
+        let ok = 0; const failed = [];
+        for (const row of rows) { if (!row.email) continue; try { await call("instantly", "create_lead", { campaign: id, email: row.email, first_name: row.first_name, last_name: row.last_name, company_name: row.company_name, skip_if_in_campaign: true }, ctxFrom(this)); ok++; } catch (e) { failed.push(`${row.email}: ${e.message}`); } }
+        emit(this, { added: ok, failed }, (d) => process.stdout.write(`✓ Added ${d.added} lead(s)${d.failed.length ? `, ${d.failed.length} failed:\n  ${d.failed.join("\n  ")}` : ""}\n`));
+      } catch (e) { fail(e); }
+    });
+  withCommonOpts(l.command("remove <ids...>")).option("-y, --yes").action(run(null, "call", (ids) => ids.length === 1 ? { op: "deleteLead", data: { id: ids[0] } } : { op: "deleteLeadsBulk", data: { ids } }, undefined, (ids) => `Remove ${ids.length} lead(s) from Instantly.`));
+  withCommonOpts(l.command("move <toCampaignId> <ids...>")).action(run(null, "move_leads", (to, ids) => ({ ids, to_campaign_id: to })));
+  withCommonOpts(l.command("status <email> <interest>")).description("Set interest: 1 interested, 2 meeting booked, 3 meeting completed, 4 won, 0 out of office, -1 not interested, -2 wrong person, -3 lost").option("--campaign <id>")
+    .action(run(null, "update_lead_status", (e, v, o) => ({ lead_email: e, interest_value: Number(v), campaign_id: o.campaign })));
+  withCommonOpts(l.command("merge <leadId> <intoLeadId>")).action(run(null, "merge_leads", (a1, b) => ({ lead_id: a1, destination_lead_id: b })));
+  withCommonOpts(l.command("lists")).action(run(null, "list_lead_lists", { limit: 100 }, (d) => process.stdout.write(table(["id", "name"], items(d).map((x) => [x.id, x.name])))));
+  withCommonOpts(l.command("list-create <name>")).action(run(null, "create_lead_list", (name) => ({ name })));
+  withCommonOpts(l.command("list-delete <id>")).option("-y, --yes").action(run(null, "delete_lead_list", (id) => ({ id }), undefined, (id) => `Delete lead list ${id}.`));
+  withCommonOpts(l.command("blocklist")).action(run(null, "list_block_list", { limit: 100 }, (d) => process.stdout.write(table(["id", "blocked"], items(d).map((x) => [x.id, x.bl_value])))));
+  withCommonOpts(l.command("block <emailOrDomain>")).action(run(null, "add_block_list", (v) => ({ bl_value: v })));
+  withCommonOpts(l.command("unblock <id>")).action(run(null, "remove_block_list", (id) => ({ id })));
+
+  // ── Tags ──
+  withCommonOpts(email.command("tags")).action(run(null, "list_tags", { limit: 100 }, (d) => process.stdout.write(table(["id", "label"], items(d).map((x) => [x.id, x.label])))));
+  withCommonOpts(email.command("labels")).action(run(null, "list_labels", { limit: 100 }, (d) => process.stdout.write(table(["id", "label"], items(d).map((x) => [x.id, x.label ?? x.name])))));
+}

package/src/commands/resources.mjs

@@ -68,6 +68,20 @@ export function registerLeads(program) {
       } catch (e) { fail(e); }
     });
 
+  withCommonOpts(leads.command("company-refresh <ids...>"))
+    .description("Refresh company news (Brave via Madnion) for up to 25 leads")
+    .option("--force", "Ignore the 14-day freshness window")
+    .action(async function (ids, opts) {
+      try {
+        const r = await call("leads", "company_refresh", { ids, force: !!opts.force }, ctxFrom(this));
+        emit(this, r, (d) => {
+          const c = d.company_refresh || {};
+          if (c.skipped) return process.stdout.write(`Skipped: ${c.reason ?? "company news is off for this workspace"}\n`);
+          process.stdout.write(`✓ ${c.enriched ?? 0} companies refreshed, ${c.skipped_fresh ?? 0} already fresh, ${(c.errors || []).length} errors\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
   withCommonOpts(leads.command("set-status <id> <status>"))
     .description("Update a lead's status")
     .action(async function (id, status) {
@@ -77,6 +91,24 @@ export function registerLeads(program) {
       } catch (e) { fail(e); }
     });
 
+  withCommonOpts(leads.command("import-engagers"))
+    .description("Import people who recently commented on your LinkedIn posts (via Taplio)")
+    .option("--max-posts <n>", "recent posts to scan (max 50)", "20")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("leads", "import_engagers", {
+          max_posts: Number(o.maxPosts),
+        }, ctxFrom(this));
+        emit(this, r, (d) => {
+          if (d.reason) return process.stdout.write(`${d.reason}\n`);
+          process.stdout.write(
+            `✓ ${d.imported} new lead(s) imported · ${d.already_known} already known · ${d.posts_scanned ?? 0} posts scanned\n`,
+          );
+        });
+      } catch (e) { fail(e); }
+    });
+
   withCommonOpts(leads.command("import"))
     .description("Bulk upsert leads from a CSV or JSON/JSONL file")
     .requiredOption("--file <path>", "leads.csv | leads.json | leads.jsonl")

package/src/index.mjs

@@ -17,6 +17,7 @@ import {
   registerExport, registerIntegrations, registerAudit, registerReports,
 } from "./commands/insights.mjs";
 import { registerFlow } from "./commands/flow.mjs";
+import { registerEmail } from "./commands/email.mjs";
 import { registerVaultSync } from "./commands/knowledge-sync.mjs";
 
 const program = new Command();
@@ -43,6 +44,7 @@ registerStrategies(program);
 registerVoice(program);
 registerBrand(program);
 registerAuthority(program);
+registerEmail(program);
 registerBriefs(program);
 registerAgents(program);
 registerIntegrations(program);