@series-a/cli 1.3.0 → 1.3.2

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/flow.mjs

@@ -0,0 +1,175 @@
+import { readFile } from "node:fs/promises";
+import { call } from "../api.mjs";
+import { emit, fail, ctxFrom, withCommonOpts, table, truncate } from "../ui.mjs";
+
+function parseCsv(text) {
+  const lines = text.split(/\r?\n/).filter((l) => l.trim().length);
+  if (!lines.length) return [];
+  const split = (line) => {
+    const out = []; let cur = ""; let q = false;
+    for (let i = 0; i < line.length; i++) {
+      const c = line[i];
+      if (q) {
+        if (c === '"' && line[i + 1] === '"') { cur += '"'; i++; }
+        else if (c === '"') { q = false; }
+        else cur += c;
+      } else {
+        if (c === ",") { out.push(cur); cur = ""; }
+        else if (c === '"') { q = true; }
+        else cur += c;
+      }
+    }
+    out.push(cur);
+    return out.map((s) => s.trim());
+  };
+  const headers = split(lines[0]).map((h) => h.toLowerCase());
+  return lines.slice(1).map((line) => {
+    const cells = split(line);
+    const row = {};
+    headers.forEach((h, i) => { row[h] = cells[i] ?? ""; });
+    return row;
+  });
+}
+
+async function loadRows(file) {
+  const text = await readFile(file, "utf8");
+  if (file.endsWith(".jsonl")) {
+    return text.split(/\r?\n/).filter(Boolean).map((l) => JSON.parse(l));
+  }
+  if (file.endsWith(".json")) {
+    const parsed = JSON.parse(text);
+    return Array.isArray(parsed) ? parsed : (parsed.leads ?? []);
+  }
+  return parseCsv(text);
+}
+
+export function registerFlow(program) {
+  withCommonOpts(program.command("campaign-flow"))
+    .description("End-to-end: import leads → create/attach sequence → launch → show status")
+    .requiredOption("--name <name>", "campaign name")
+    .requiredOption("--file <path>", "leads CSV / JSON / JSONL")
+    .option("--description <text>", "campaign description")
+    .option("--goal <text>", "campaign goal")
+    .option("--persona <tag>", "default persona_tag for imported leads")
+    .option("--source <s>", "default lead source", "cli-flow")
+    .option("--sequence <id>", "attach an existing sequence (otherwise picks most recent active)")
+    .option("--senders <csv>", "comma-separated sender_account_ids")
+    .option("--daily-limit <n>", "daily send cap", "25")
+    .option("--launch", "activate the campaign immediately after setup", false)
+    .option("--dry-run", "print plan only, do not call the API", false)
+    .action(async function (opts) {
+      const ctx = ctxFrom(this);
+      const steps = [];
+      const log = (msg) => { if (!this.optsWithGlobals().json) process.stdout.write(msg); };
+      try {
+        // 1. Load + import leads
+        const rows = await loadRows(opts.file);
+        if (!rows.length) return fail(new Error(`No leads found in ${opts.file}`));
+        if (opts.persona) rows.forEach((r) => { r.persona_tag = r.persona_tag || opts.persona; });
+        rows.forEach((r) => { r.source = r.source || opts.source; });
+
+        if (opts.dryRun) {
+          log(`DRY RUN — would import ${rows.length} leads and create campaign "${opts.name}"\n`);
+          return emit(this, { dry_run: true, lead_count: rows.length, name: opts.name }, () => {});
+        }
+
+        log(`→ Importing ${rows.length} leads…\n`);
+        let imported = 0;
+        const importedIds = [];
+        for (let i = 0; i < rows.length; i += 200) {
+          const chunk = rows.slice(i, i + 200);
+          const r = await call("leads", "bulk_upsert", { leads: chunk }, ctx);
+          imported += r.count ?? 0;
+          (r.leads || r.upserted || []).forEach((l) => l?.id && importedIds.push(l.id));
+        }
+        steps.push({ step: "import_leads", imported, total: rows.length });
+        log(`  ✓ Upserted ${imported}/${rows.length} leads\n`);
+
+        // Fallback: re-fetch ids if backend didn't return them
+        let leadIds = importedIds;
+        if (!leadIds.length) {
+          const list = await call("leads", "list", {
+            persona_tag: opts.persona, limit: Math.min(rows.length, 500),
+          }, ctx);
+          leadIds = (list.leads || []).map((l) => l.id).filter(Boolean);
+        }
+
+        // 2. Resolve sequence
+        let sequenceId = opts.sequence;
+        if (!sequenceId) {
+          const seqs = await call("sequences", "list", { limit: 50 }, ctx);
+          const active = (seqs.sequences || []).find((s) => s.status === "active")
+                       || (seqs.sequences || [])[0];
+          if (!active) return fail(new Error("No sequence found — pass --sequence <id> or create one first"));
+          sequenceId = active.id;
+          log(`→ Using sequence: ${active.name} (${truncate(sequenceId, 8)})\n`);
+        }
+        steps.push({ step: "resolve_sequence", sequence_id: sequenceId });
+
+        // 3. Create campaign
+        log(`→ Creating campaign "${opts.name}"…\n`);
+        const created = await call("campaigns", "create", {
+          name: opts.name,
+          description: opts.description,
+          goal: opts.goal,
+          sequence_id: sequenceId,
+          sender_accounts: opts.senders ? opts.senders.split(",").map((s) => s.trim()).filter(Boolean) : [],
+          daily_send_limit: Number(opts.dailyLimit),
+        }, ctx);
+        const campaignId = created.campaign?.id;
+        if (!campaignId) return fail(new Error("Campaign create returned no id"));
+        steps.push({ step: "create_campaign", campaign_id: campaignId });
+        log(`  ✓ Campaign ${truncate(campaignId, 8)} created\n`);
+
+        // 4. Attach leads
+        if (leadIds.length) {
+          log(`→ Attaching ${leadIds.length} leads to campaign…\n`);
+          const add = await call("campaigns", "add_leads", {
+            campaign_id: campaignId, lead_ids: leadIds,
+          }, ctx);
+          steps.push({ step: "add_leads", added: add.added, requested: add.requested });
+          log(`  ✓ Added ${add.added}/${add.requested} (${add.valid} valid in workspace)\n`);
+        }
+
+        // 5. Launch (optional)
+        let launched = null;
+        if (opts.launch) {
+          log(`→ Launching campaign…\n`);
+          launched = await call("campaigns", "launch", { campaign_id: campaignId }, ctx);
+          steps.push({ step: "launch", status: launched.campaign?.status });
+          log(`  ✓ Status → ${launched.campaign?.status}\n`);
+        }
+
+        // 6. Final status
+        const finalShow = await call("campaigns", "get", { id: campaignId }, ctx);
+        const c = finalShow.campaign || {};
+        const summary = {
+          campaign_id: campaignId,
+          name: c.name,
+          status: c.status,
+          sequence_id: c.sequence_id,
+          daily_send_limit: c.daily_send_limit,
+          sender_accounts: c.sender_accounts || [],
+          leads_attached: c.lead_count ?? leadIds.length,
+          steps,
+        };
+
+        emit(this, summary, (d) => {
+          process.stdout.write("\n" + table(
+            ["field", "value"],
+            [
+              ["campaign", `${d.name} (${truncate(d.campaign_id, 8)})`],
+              ["status", d.status],
+              ["sequence", truncate(d.sequence_id, 8)],
+              ["leads", d.leads_attached],
+              ["senders", (d.sender_accounts || []).length],
+              ["daily cap", d.daily_send_limit],
+            ],
+          ) + "\n");
+          process.stdout.write(opts.launch
+            ? `✓ Campaign live — monitor with: advisoros campaigns show ${campaignId}\n`
+            : `✓ Campaign ready (draft) — launch with: advisoros campaigns launch ${campaignId}\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+}