argorant 0.3.0 → 0.4.0

package/bin/argorant.js

@@ -67,15 +67,18 @@ const VALUE_FLAGS = {
   "--company": "company_name",
   "--domain": "company_domain",
 };
-// 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, file: null, column: 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;
@@ -85,6 +88,8 @@ function parseArgs(argv) {
     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("=")) {
@@ -302,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) {
@@ -331,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));
@@ -387,7 +401,7 @@ async function cmdVerifyFile(args, key) {
   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? Fresh checks use your verification-check pool; addresses checked in the last 60 days are free. [y/N] `);
+    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 = [];
@@ -406,7 +420,40 @@ async function cmdVerifyFile(args, key) {
   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 cache hits)`)}`);
+  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() {
@@ -424,15 +471,18 @@ ${bold("COMMANDS")}
   ${cyan("search")} "<query>" -n 10     Preview matches, details redacted ${dim("(free)")}
   ${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("(60-day re-checks free)")}
+  ${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>
-  --has-phone        --has-linkedin       --has-email
+  --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")}
@@ -469,6 +519,7 @@ async function main() {
     search: cmdSearch,
     reveal: cmdReveal,
     export: cmdExport,
+    list: cmdList,
     verify: cmdVerify,
   };
   const fn = table[cmd];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argorant",
-  "version": "0.3.0",
+  "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"