@series-a/cli 1.3.1 → 1.3.2

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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.
 
+## 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.3.2",
   "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

@@ -77,6 +77,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);