argorant 0.2.0 → 0.4.0

package/bin/argorant.js

@@ -2,7 +2,7 @@
 "use strict";
 
 // Argorant CLI — a thin, dependency-free wrapper over the Argorant REST API.
-// Search, count, reveal, and export verified B2B contacts from the terminal.
+// Search, count, reveal, export, and verify B2B contacts from the terminal.
 // Auth: an Argorant API key (ag_live_*) via `argorant login`, or ARGORANT_API_KEY.
 
 const https = require("https");
@@ -66,24 +66,30 @@ const VALUE_FLAGS = {
   "--city": "city",
   "--company": "company_name",
   "--domain": "company_domain",
-  "--verify-status": "verify_status",
 };
-// Boolean filter flags (presence => "true").
+// Boolean filter flags (presence => "true"). --verified-only is positive intent
+// only (deliverable contacts); there is deliberately NO flag to query invalid or
+// any raw verification status — that is never exposed on any surface.
 const BOOL_FLAGS = {
   "--has-phone": "has_phone",
   "--has-linkedin": "has_linkedin",
   "--has-email": "has_email",
+  "--verified-only": "verified_only",
 };
 
 function parseArgs(argv) {
-  const out = { _: [], filters: {}, limit: null, output: null, json: false, yes: false, base: DEFAULT_BASE };
+  const out = { _: [], filters: {}, limit: null, output: null, file: null, column: null, json: false, yes: false, base: DEFAULT_BASE, name: null, includeExported: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--json") out.json = true;
     else if (a === "--yes" || a === "-y") out.yes = true;
     else if (a === "-n" || a === "--limit") out.limit = parseInt(argv[++i], 10);
     else if (a === "-o" || a === "--output") out.output = argv[++i];
+    else if (a === "-f" || a === "--file") out.file = argv[++i];
+    else if (a === "--column") out.column = argv[++i];
     else if (a === "--base") out.base = argv[++i];
+    else if (a === "--name") out.name = argv[++i];
+    else if (a === "--include-exported") out.includeExported = true;
     else if (a in VALUE_FLAGS) out.filters[VALUE_FLAGS[a]] = argv[++i];
     else if (a in BOOL_FLAGS) out.filters[BOOL_FLAGS[a]] = "true";
     else if (a.startsWith("--") && a.includes("=")) {
@@ -301,7 +307,16 @@ async function cmdExport(args) {
     const ans = await prompt(`Export up to ${bold(limit)} verified contacts to ${bold(dest)}? Uses quota/credits. [y/N] `);
     if (!/^y(es)?$/i.test(ans)) return console.log(dim("aborted."));
   }
-  const create = await request("POST", args.base, "/api/mcp/exports/create", { key, body: { limit, filters: args.filters } });
+  // Match the MCP/app defaults so the CLI yields the same rows: business email
+  // present by default, and skip rows already exported (override with
+  // --include-exported). Verification stays live at export time — only deliverable
+  // rows are billed; no verification-status filter is exposed.
+  const exportFilters = { ...args.filters };
+  if (exportFilters.has_email === undefined) exportFilters.has_email = "true";
+  const create = await request("POST", args.base, "/api/mcp/exports/create", {
+    key,
+    body: { limit, filters: exportFilters, exclude_previously_exported: !args.includeExported },
+  });
   const job = need(create, "export");
   const statusPath = job.status_api_path || (job.job_id ? `/api/mcp/exports/${job.job_id}` : null);
   if (!statusPath) {
@@ -330,7 +345,7 @@ async function cmdExport(args) {
   if (!args.json) process.stdout.write("\n");
   if (!downloadPath) {
     if (args.json) return console.log(JSON.stringify(job, null, 2));
-    return console.log("Export ready but no download path returned. Check `argorant export-list`.");
+    return console.log("Export ready but no download path returned yet. Re-run with --json to inspect the job, or check the Exports page in the app.");
   }
   await downloadTo(args.base, downloadPath, key, dest);
   if (args.json) return console.log(JSON.stringify({ ok: true, file: dest, job_id: job.job_id }, null, 2));
@@ -344,6 +359,103 @@ async function cmdExport(args) {
   console.log(green("✓") + ` Saved ${rows != null ? bold(rows.toLocaleString()) + " rows → " : ""}${bold(dest)}`);
 }
 
+// ---- verify: external email verification (own lists) — the verification pool,
+// separate from contact credits. 60-day re-checks are free. ----
+const EMAIL_RE = /[^\s,;"']+@[^\s,;"']+\.[^\s,;"']+/;
+
+async function cmdVerify(args) {
+  const key = requireKey();
+  if (args.file) return cmdVerifyFile(args, key);
+  const email = (args._[0] || args.filters.q || "").trim().toLowerCase();
+  if (!email || !email.includes("@")) {
+    die('usage: argorant verify <email>   |   argorant verify --file emails.csv [-o out.csv]');
+  }
+  const res = await request("POST", args.base, "/api/mcp/email/verify", { key, body: { email } });
+  const r = need(res, "verify");
+  if (args.json) return console.log(JSON.stringify(r, null, 2));
+  const tag = r.deliverable ? green(r.status) : dim(r.status);
+  console.log(`  ${bold(email)}  →  ${tag}${r.deliverable ? "  " + green("✓ deliverable") : ""}`);
+}
+
+async function cmdVerifyFile(args, key) {
+  let text;
+  try { text = fs.readFileSync(args.file, "utf8"); } catch { die(`cannot read file: ${args.file}`); }
+  const lines = text.split(/\r?\n/).filter((l) => l.trim());
+  if (!lines.length) die("file is empty");
+  // Use the named/auto-detected email column if the file looks like a CSV with a
+  // header; otherwise scan every line for an address.
+  const header = lines[0].split(",").map((h) => h.trim().toLowerCase().replace(/^["']|["']$/g, ""));
+  const colIdx = args.column
+    ? header.indexOf(args.column.toLowerCase())
+    : header.findIndex((h) => h === "email" || h.includes("email"));
+  let emails = [];
+  if (colIdx >= 0) {
+    for (let i = 1; i < lines.length; i++) {
+      const m = (lines[i].split(",")[colIdx] || "").match(EMAIL_RE);
+      if (m) emails.push(m[0].toLowerCase());
+    }
+  } else {
+    for (const l of lines) { const m = l.match(EMAIL_RE); if (m) emails.push(m[0].toLowerCase()); }
+  }
+  emails = [...new Set(emails)];
+  if (!emails.length) die("no email addresses found in file (try --column <name>)");
+  const out = args.output || "argorant-verified.csv";
+  if (!args.yes && !args.json && process.stdin.isTTY) {
+    const ans = await prompt(`Verify ${bold(emails.length.toLocaleString())} emails? You're billed only for fresh checks from your verification-check pool; recent re-checks are free. [y/N] `);
+    if (!/^y(es)?$/i.test(ans)) return console.log(dim("aborted."));
+  }
+  const all = [];
+  let charged = 0, cached = 0;
+  for (let i = 0; i < emails.length; i += 500) {
+    const chunk = emails.slice(i, i + 500);
+    const res = await request("POST", args.base, "/api/mcp/email/verify/batch", { key, body: { emails: chunk } });
+    const r = need(res, "verify");
+    charged += r.checks_charged || 0;
+    cached += r.cached || 0;
+    for (const row of r.results || []) all.push(row);
+    if (!args.json) process.stdout.write(`\r${dim(`verified ${Math.min(i + 500, emails.length).toLocaleString()}/${emails.length.toLocaleString()}`)}`);
+  }
+  if (!args.json) process.stdout.write("\n");
+  if (args.json) return console.log(JSON.stringify({ ok: true, total: all.length, checks_charged: charged, cached, results: all }, null, 2));
+  const csv = ["email,status,deliverable", ...all.map((r) => `${r.email},${r.status},${r.deliverable}`)].join("\n") + "\n";
+  fs.writeFileSync(out, csv);
+  const deliverable = all.filter((r) => r.deliverable).length;
+  console.log(green("✓") + ` ${bold(all.length.toLocaleString())} verified → ${bold(out)}  ${dim(`(${deliverable.toLocaleString()} deliverable · ${charged.toLocaleString()} checks billed · ${cached.toLocaleString()} free)`)}`);
+}
+
+// ---- list: save & inspect reusable lead lists (parity with MCP/app). Creating a
+// filtered list is free and does NOT reveal contacts — the server counts the
+// matches itself, so the list reports its real size right away. ----
+async function cmdList(args) {
+  const key = requireKey();
+  const sub = (args._[0] || "").toLowerCase();
+  if (sub === "create") {
+    const name = (args.name || "").trim();
+    if (!name) die('usage: argorant list create --name "My list" [filters]   (e.g. --title CEO --country Germany)');
+    delete args.filters.q; // the "create" subcommand word leaks into q via parseArgs
+    const body = { name, filters: args.filters, record_type: "person", selection_mode: "filtered" };
+    const res = await request("POST", args.base, "/api/mcp/lists/create", { key, body });
+    const r = need(res, "list create");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    const total = Number(r.snapshot_total || 0);
+    console.log(green("✓") + ` Created list ${bold("#" + r.list_id)} ${dim("“" + r.name + "”")} — ${bold(total.toLocaleString())} matching contacts`);
+    console.log(dim(`Export it with:  argorant export ${Object.entries(args.filters).filter(([, v]) => v).map(([k, v]) => `--${k.replace(/_/g, "-")} ${/\s/.test(String(v)) ? `"${v}"` : v}`).join(" ")} -o leads.csv`));
+    return;
+  }
+  if (sub === "status" || sub === "show" || sub === "get") {
+    const id = args._[1] || args.name;
+    if (!id) die("usage: argorant list status <list_id>");
+    const res = await request("GET", args.base, `/api/mcp/lists/${encodeURIComponent(id)}`, { key });
+    const r = need(res, "list status");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    const total = Number(r.snapshot_total ?? r.item_count ?? 0);
+    console.log(`${bold("List #" + (r.list_id ?? id))}  ${dim("“" + (r.name || "—") + "”")}`);
+    console.log(`  ${bold(total.toLocaleString())} contacts · ${dim((r.selection_mode || "filtered") + " · " + (r.record_type || "person"))}`);
+    return;
+  }
+  die("usage: argorant list create --name \"…\" [filters]   |   argorant list status <id>");
+}
+
 function help() {
   const p = bold("argorant");
   console.log(`
@@ -357,15 +469,20 @@ ${bold("COMMANDS")}
   ${cyan("whoami")}                     Account, scopes, and daily quota
   ${cyan("count")} "<query>"            Count matching contacts        ${dim("(free)")}
   ${cyan("search")} "<query>" -n 10     Preview matches, details redacted ${dim("(free)")}
-  ${cyan("reveal")} "<query>" -n 25     Reveal full contact details    ${dim("(uses quota)")}
-  ${cyan("export")} "<query>" -n 1000 -o leads.csv   Verified CSV export ${dim("(uses quota)")}
+  ${cyan("reveal")} "<query>" -n 25     Reveal full contact details    ${dim("(uses credits; live-verified, pay only for deliverable)")}
+  ${cyan("export")} "<query>" -n 1000 -o leads.csv   Verified CSV export ${dim("(uses credits)")}
+  ${cyan("list create")} --name "<n>" [filters]      Save a reusable list ${dim("(free)")}
+  ${cyan("list status")} <id>           Show a saved list's size       ${dim("(free)")}
+  ${cyan("verify")} <email>             Verify one of your own emails  ${dim("(verification pool)")}
+  ${cyan("verify")} --file emails.csv -o out.csv      Bulk-verify your own list ${dim("(recent re-checks free)")}
 
 ${bold("FILTERS")}
   --title <t>        --exclude-title <t>  --seniority <s>    --department <d>
   --industry <i>     --country <c>        --geography <r>    --state <s>
-  --city <c>         --company <name>     --domain <domain>  --verify-status <v>
-  --has-phone        --has-linkedin       --has-email
+  --city <c>         --company <name>     --domain <domain>
+  --has-phone        --has-linkedin       --has-email          --verified-only
   ${dim("--title is abbreviation-aware (CFO ↔ Chief Financial Officer).")}
+  ${dim("--verified-only keeps deliverable contacts; export verifies live & bills only valid.")}
   ${dim("--country / --geography accept regions: Europe, EMEA, DACH, Nordics, APAC, LATAM, GCC…")}
 
 ${bold("OPTIONS")}
@@ -377,6 +494,8 @@ ${bold("EXAMPLES")}
   ${p} count "fintech CFOs in germany"
   ${p} search "heads of procurement" --country Germany -n 10
   ${p} export --industry fintech --title CFO --country Germany -n 500 -o cfos.csv
+  ${p} verify ceo@stripe.com
+  ${p} verify --file my-list.csv -o verified.csv
 
   Docs: ${cyan("https://argorant.com/docs/cli")}
 `);
@@ -400,6 +519,8 @@ async function main() {
     search: cmdSearch,
     reveal: cmdReveal,
     export: cmdExport,
+    list: cmdList,
+    verify: cmdVerify,
   };
   const fn = table[cmd];
   if (!fn) die(`unknown command: ${cmd}\nRun \`argorant help\` for usage.`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "argorant",
-  "version": "0.2.0",
-  "description": "Search, count, reveal, and export verified B2B contacts from the Argorant database \u2014 from your terminal, scripts, or coding agent.",
+  "version": "0.4.0",
+  "description": "Search, count, reveal, export, and verify B2B contacts from the Argorant database \u2014 from your terminal, scripts, or coding agent.",
   "bin": {
     "argorant": "bin/argorant.js"
   },