argorant 0.14.0 → 0.15.0

package/bin/argorant.js

@@ -54,28 +54,138 @@ function resolveKey() {
 }
 
 // ---- arg parsing ----
-// Flags that map to API filter params. Value flags take the next token.
-const VALUE_FLAGS = {
-  "--title": "title",
-  "--exclude-title": "exclude_title",
-  "--seniority": "seniority",
-  "--department": "departments",
-  "--departments": "departments",
-  "--industry": "industry",
-  // --keywords is the highest-recall door in the index (matches source keyword
-  // tags + derived company tags, comma = OR). Measured against real segments it
-  // beats --industry by 2-4x, so it leads the docs and examples below.
-  "--keywords": "keywords",
+// ---- one filter vocabulary (0.15.0) ----
+// Every filter-taking command (count, search, reveal, export, list create, lists create, lists add,
+// companies, company people, campaigns leads add) reads its filters from ONE map, built from the
+// filter schema the API publishes (bin/search-filters.json, the same file the API, the app and the
+// connector use). Each list filter has an include flag and an exclude flag, usable together.
+const FILTER_SCHEMA = (() => {
+  try {
+    return require("./search-filters.json");
+  } catch {
+    return { filters: [], modes: {}, cli_flags: {} };
+  }
+})();
+// Older spellings that keep working.
+const FILTER_ALIASES = {
   "--keyword": "keywords",
-  "--country": "country",
-  // --geography is an alias for --country; the API expands regions like
-  // "Europe", "EMEA", "DACH", "APAC" into their member countries.
+  "--exclude-keyword": "exclude_keywords",
+  "--departments": "departments",
+  "--exclude-departments": "exclude_departments",
   "--geography": "country",
   "--region": "country",
-  "--state": "state",
-  "--city": "city",
+  "--exclude-geography": "exclude_country",
+  "--exclude-region": "exclude_country",
   "--company": "company_name",
-  "--domain": "company_domain",
+  "--company-domain": "company_domain",
+  "--exclude-company-domain": "exclude_company_domain",
+  "--employee-range": "employee_range",
+  "--technologies": "technologies",
+  "--technology": "technologies",
+  "--near-place": "near_place",
+};
+const BOOL_PARAMS = new Set(FILTER_SCHEMA.filters.filter((f) => f.kind === "boolean").map((f) => f.include));
+// flag -> API parameter, value flags only (booleans below). --near takes a place (a city or postal code such as
+// "Denver, Colorado", or a place id) or "lat,lon".
+const FILTER_VALUE_FLAGS = (() => {
+  const out = {};
+  for (const [param, flag] of Object.entries(FILTER_SCHEMA.cli_flags || {})) {
+    if (!BOOL_PARAMS.has(param)) out[flag] = param;
+  }
+  out["--near"] = "near";
+  return { ...out, ...FILTER_ALIASES };
+})();
+const FILTER_BOOL_FLAGS = (() => {
+  const out = {};
+  for (const [param, flag] of Object.entries(FILTER_SCHEMA.cli_flags || {})) if (BOOL_PARAMS.has(param)) out[flag] = param;
+  return out;
+})();
+// Finite values (checked here, before any request): parameter -> [{value, label}].
+const FILTER_ENUMS = (() => {
+  const out = {};
+  for (const f of FILTER_SCHEMA.filters || []) {
+    if (f.kind === "enum_list" && Array.isArray(f.values)) {
+      for (const p of [f.include, f.exclude]) if (p) out[p] = f.values;
+    }
+    if (f.kind === "radius") {
+      if (Array.isArray(f.units)) out.radius_unit = f.units;
+      if (Array.isArray(f.targets)) out.radius_target = f.targets;
+    }
+  }
+  for (const [name, m] of Object.entries(FILTER_SCHEMA.modes || {})) if (Array.isArray(m.values)) out[name] = m.values;
+  return out;
+})();
+const SINGLE_VALUE = new Set(["title_match", "exclude_title_match", "keyword_scope", "radius_unit", "radius_target"]);
+// Filters for company records (people-only ones are refused by the API on company searches).
+const COMPANY_PARAMS = new Set([
+  "q", "industry", "exclude_industry", "industries", "exclude_industries", "country", "exclude_country", "state",
+  "exclude_state", "city", "exclude_city", "company_name", "company_domain", "exclude_company_domain", "employee_range",
+  "employees_min", "employees_max", "revenue_band", "revenue_min", "revenue_max", "keywords", "exclude_keywords",
+  "keyword_scope", "technologies", "near", "near_place", "near_lat", "near_lon", "radius", "radius_unit", "radius_target",
+]);
+// What `company <domain>` passes on (the people at one company).
+const COMPANY_PEOPLE_PARAMS = new Set([
+  "title", "exclude_title", "title_match", "exclude_title_match", "seniority", "exclude_seniority", "departments",
+  "exclude_departments", "country", "exclude_country", "exclude_state", "exclude_city", "gender", "income_band",
+]);
+function flagOfParam(param) {
+  return (FILTER_SCHEMA.cli_flags || {})[param] || `--${String(param).replace(/_/g, "-")}`;
+}
+function fold(v) {
+  return String(v).normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().trim();
+}
+// Check and spell finite values the canonical way; plain error listing what is allowed.
+function checkEnum(param, raw) {
+  const allowed = FILTER_ENUMS[param];
+  if (!allowed) return raw;
+  const match = (v) => allowed.find((a) => fold(a.value) === fold(v) || fold(a.label) === fold(v) || fold(a.value).replace(/[\s,]/g, "") === fold(v).replace(/[\s,]/g, ""));
+  const whole = match(String(raw).trim());
+  if (whole) return whole.value; // a label with a comma in it, such as 501-1,000
+  const parts = SINGLE_VALUE.has(param) ? [String(raw)] : String(raw).split(",");
+  const out = [];
+  for (const part of parts) {
+    const v = part.trim();
+    if (!v) continue;
+    const hit = match(v);
+    if (!hit) die(`${flagOfParam(param)} takes: ${allowed.map((a) => a.value).join(", ")} (got "${v}").`);
+    if (!out.includes(hit.value)) out.push(hit.value);
+  }
+  return out.join(",");
+}
+// The filters of one command, ready to send: values checked, --near split.
+function finishFilters(filters) {
+  const out = {};
+  for (const [k, v] of Object.entries(filters || {})) {
+    if (v === undefined || v === null || v === "") continue;
+    out[k] = typeof v === "string" ? checkEnum(k, v) : v;
+  }
+  if (out.near !== undefined) {
+    const near = String(out.near).trim();
+    delete out.near;
+    const m = near.match(/^(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)$/);
+    if (m) {
+      out.near_lat = m[1];
+      out.near_lon = m[2];
+    } else {
+      out.near_place = near;
+    }
+  }
+  const hasPlace = out.near_place || (out.near_lat !== undefined && out.near_lon !== undefined);
+  if (out.radius !== undefined && !hasPlace) die("--radius needs a place: --near \"Denver, Colorado\" or --near <lat,lon>.");
+  if (hasPlace && out.radius === undefined) die("--near needs a distance: add --radius, for example --radius 25.");
+  return out;
+}
+// Collect the filters a readFlags() result holds for a flag map.
+function collectFilters(args, valueFlags, boolFlags = FILTER_BOOL_FLAGS) {
+  const out = {};
+  for (const field of new Set(Object.values(valueFlags))) if (args[field] !== undefined && args[field] !== "") out[field] = args[field];
+  for (const field of new Set(Object.values(boolFlags))) if (args[field]) out[field] = "true";
+  return finishFilters(out);
+}
+
+// Flags that map to API filter params for the generic parser. Value flags take the next token.
+const VALUE_FLAGS = {
+  ...FILTER_VALUE_FLAGS,
   "--website": "website",
   // Used by `enrich` (email → full profile). Harmless on the other commands,
   // which simply ignore an unknown query field.
@@ -85,9 +195,7 @@ const VALUE_FLAGS = {
 // 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",
+  ...FILTER_BOOL_FLAGS,
   "--verified-only": "verified_only",
 };
 
@@ -105,16 +213,6 @@ function setGrade(out, v) {
   out.gradeExplicit = true;
 }
 
-// --exclude-title is fully applied by `export` and `list create` today (the
-// platform forwards it into the title-exclusion query on those two paths).
-// `count`, `search`, and `reveal` go through a separate read path that does
-// not yet apply it (see GODMODE-PLAN.md). Warn instead of silently dropping
-// a filter the user asked for.
-function warnExcludeTitleGap(filters) {
-  if (filters.exclude_title) {
-    warn(`--exclude-title is not applied by this command yet (platform-side gap) - it works with \`export\` and \`list create\`.`);
-  }
-}
 function warnGradeGap(scope) {
   if (scope === "browse") warn(`--grade has no effect on count/search - grading only applies at reveal/export time.`);
   else if (scope === "reveal") warn(`--grade is coming soon for reveal - it currently always returns the platform's standard deliverable set.`);
@@ -178,6 +276,7 @@ function parseArgs(argv) {
   }
   // Free-text positional → q
   if (out._.length) out.filters.q = out._.join(" ");
+  out.filters = finishFilters(out.filters);
   return out;
 }
 
@@ -432,6 +531,8 @@ function need(res, what) {
     const wait = Number.isFinite(ra) && ra > 0 ? ` Try again in ${ra === 1 ? "1 second" : fmtWait(Math.ceil(ra))}.` : "";
     die(`${msg || "too many requests right now, or today's limit is used up."}${wait}${ref}`, EXIT.RATE_LIMIT);
   }
+  const notReady = res.res && res.res.headers && res.res.headers["x-argorant-filter-not-ready"];
+  if (notReady) die(`${msg || "This filter is not ready yet."}\nRun \`argorant filters\` to see which filters can be used now.${ref}`);
   die(`${msg || `${what} failed (HTTP ${res.status}).`}${ref}`);
 }
 
@@ -561,7 +662,6 @@ async function cmdWhoami(args) {
 
 async function cmdCount(args) {
   const key = requireKey();
-  warnExcludeTitleGap(args.filters);
   if (args.gradeExplicit) warnGradeGap("browse");
   const res = await request("GET", args.base, "/api/mcp/people/count", { key, query: args.filters });
   const r = need(res, "count");
@@ -580,13 +680,13 @@ async function cmdCompany(args) {
   if (!domain || !domain.includes(".")) {
     die("usage: argorant company <company.com> [--title <role>] [-n 5] [--json]");
   }
-  const query = {
-    title: args.filters.title,
-    seniority: args.filters.seniority,
-    departments: args.filters.departments,
-    country: args.filters.country,
-    limit: args.limit || 5,
-  };
+  const query = { limit: args.limit || 5 };
+  const ignored = [];
+  for (const [k, v] of Object.entries(args.filters)) {
+    if (COMPANY_PEOPLE_PARAMS.has(k)) query[k] = v;
+    else if (!["company_domain", "q", "website"].includes(k)) ignored.push(flagOfParam(k));
+  }
+  if (ignored.length) die(`\`company\` looks at one company's people; it does not take ${ignored.join(", ")}. Use \`count\` or \`search\` with --domain instead.`);
   const res = await request(
     "GET",
     args.base,
@@ -615,7 +715,6 @@ async function cmdCompany(args) {
 
 async function cmdSearch(args) {
   const key = requireKey();
-  warnExcludeTitleGap(args.filters);
   if (args.gradeExplicit) warnGradeGap("browse");
   const query = { ...args.filters, limit: args.limit || 5 };
   const res = await request("GET", args.base, "/api/mcp/people/preview", { key, query });
@@ -768,7 +867,6 @@ function phoneLine(p) {
 
 async function cmdReveal(args) {
   const key = requireKey();
-  warnExcludeTitleGap(args.filters);
   if (args.gradeExplicit) warnGradeGap("reveal");
   const limit = args.limit || 10;
   const pricing = args.phones ? await phonePricing(args, key) : null;
@@ -1222,9 +1320,16 @@ async function cmdList(args) {
     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 fill = await listFill(args.base, key, r.list_id, r);
+    if (fill && fill.filling) {
+      console.log(green("✓") + ` Created list ${bold("#" + r.list_id)} ${dim("“" + r.name + "”")}`);
+      console.log(`  ${fillLine(fill)}`);
+      console.log(dim(`Check it:  argorant lists show ${r.list_id}`));
+      return;
+    }
     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`));
+    console.log(dim(`Export it with:  argorant export ${Object.entries(args.filters).filter(([, v]) => v).map(([k, v]) => (k === "q" ? (/\s/.test(String(v)) ? `"${v}"` : String(v)) : FILTER_BOOL_FLAGS[flagOfParam(k)] ? flagOfParam(k) : `${flagOfParam(k)} ${/\s/.test(String(v)) ? `"${v}"` : v}`)).join(" ")} -o leads.csv`));
     return;
   }
   if (sub === "status" || sub === "show" || sub === "get") {
@@ -1239,7 +1344,9 @@ async function cmdList(args) {
     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"))}`);
+    const fill = await listFill(args.base, key, String(id).trim(), null);
+    if (fill && (fill.filling || (fill.fill && fill.fill.status === "failed"))) console.log(`  ${fillLine(fill)}`);
+    else 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>");
@@ -1270,29 +1377,8 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
 // filter-enroll endpoint doesn't accept, e.g. --verified-only), plus --query
 // as an explicit alias for free-text `q` (clearer than a bare positional in a
 // command that already takes a campaign name/id as its first positional).
-const CAMPAIGN_FILTER_VALUE_FLAGS = {
-  "--query": "q",
-  "--title": "title",
-  "--exclude-title": "exclude_title",
-  "--seniority": "seniority",
-  "--department": "departments",
-  "--departments": "departments",
-  "--industry": "industry",
-  "--keywords": "keywords",
-  "--keyword": "keywords",
-  "--country": "country",
-  "--geography": "country",
-  "--region": "country",
-  "--state": "state",
-  "--city": "city",
-  "--company": "company_name",
-  "--domain": "company_domain",
-};
-const CAMPAIGN_FILTER_BOOL_FLAGS = {
-  "--has-phone": "has_phone",
-  "--has-linkedin": "has_linkedin",
-  "--has-email": "has_email",
-};
+const CAMPAIGN_FILTER_VALUE_FLAGS = { "--query": "q", ...FILTER_VALUE_FLAGS };
+const CAMPAIGN_FILTER_BOOL_FLAGS = { ...FILTER_BOOL_FLAGS };
 
 // Minimal flag reader shared by every `campaigns` subcommand: pulls out the
 // universal --json/--yes/--base plus whatever value/bool flags the caller
@@ -1721,9 +1807,7 @@ async function campaignsLeads(argv) {
   }
 
   // Filter enrollment straight from the database: operator keys.
-  const filters = {};
-  for (const field of Object.values(CAMPAIGN_FILTER_VALUE_FLAGS)) if (args[field]) filters[field] = args[field];
-  for (const field of Object.values(CAMPAIGN_FILTER_BOOL_FLAGS)) if (args[field]) filters[field] = "true";
+  const filters = collectFilters(args, CAMPAIGN_FILTER_VALUE_FLAGS, CAMPAIGN_FILTER_BOOL_FLAGS);
   if (!Object.keys(filters).length) die(usage);
   const body = { filters };
   if (args.limit) body.limit = parseLimit(args.limit, "-n");
@@ -3003,25 +3087,11 @@ async function cmdFind(argv) {
 
 const V1 = "/api/v1";
 const PAGE_FLAGS = { "-n": "limit", "--limit": "limit", "--cursor": "cursor", "--offset": "offset" };
-const COMPANY_FILTER_FLAGS = {
-  "--query": "q",
-  "--q": "q",
-  "--industry": "industry",
-  "--industries": "industries",
-  "--country": "country",
-  "--geography": "country",
-  "--region": "country",
-  "--state": "state",
-  "--city": "city",
-  "--company": "company_name",
-  "--domain": "company_domain",
-  "--employees": "employee_range",
-  "--employee-range": "employee_range",
-  "--keywords": "keywords",
-  "--keyword": "keywords",
-  "--technologies": "technologies",
-  "--technology": "technologies",
-};
+const COMPANY_FILTER_FLAGS = (() => {
+  const out = { "--query": "q", "--q": "q" };
+  for (const [flag, param] of Object.entries(FILTER_VALUE_FLAGS)) if (COMPANY_PARAMS.has(param)) out[flag] = param;
+  return out;
+})();
 const LOOKUP_KINDS = ["industries", "countries", "keywords", "technologies", "titles"];
 const LOOKUP_ALIASES = { industry: "industries", country: "countries", keyword: "keywords", technology: "technologies", tech: "technologies", title: "titles" };
 
@@ -3192,29 +3262,14 @@ ${bold("Argorant lists")} - saved lists of people (free to create and browse)
   ${p} export <id> [-n 1000] [-o leads.csv] [--include-exported] [--include-phones] [--no-wait] [--yes]
       ${dim("1 credit per valid contact; with --include-phones 10 credits per phone number returned")}
 
-  filters for create: --title --seniority --department --industry --keywords --country --state --city --company --domain
+  ${p} add <id> [filters]                   ${dim("adds every match of a search; people already in it are skipped")}
+
+  filters for create and add: the same as everywhere (argorant help, FILTERS), include and exclude
   ${dim("Add --json to any command for the raw answer.")}
 `);
 }
 
-const LIST_FILTER_FLAGS = {
-  "--query": "q",
-  "--title": "title",
-  "--exclude-title": "exclude_title",
-  "--seniority": "seniority",
-  "--department": "departments",
-  "--departments": "departments",
-  "--industry": "industry",
-  "--keywords": "keywords",
-  "--keyword": "keywords",
-  "--country": "country",
-  "--geography": "country",
-  "--region": "country",
-  "--state": "state",
-  "--city": "city",
-  "--company": "company_name",
-  "--domain": "company_domain",
-};
+const LIST_FILTER_FLAGS = { "--query": "q", ...FILTER_VALUE_FLAGS };
 
 function listLine(l) {
   const size = Number(l.snapshot_total || l.item_count || 0);
@@ -3245,20 +3300,40 @@ async function cmdLists(argv) {
     return;
   }
   if (sub === "create" || sub === "new") {
-    const args = readFlags(rest, { ...LIST_FILTER_FLAGS, "--name": "name" }, { "--has-phone": "has_phone", "--has-linkedin": "has_linkedin", "--has-email": "has_email" });
+    const args = readFlags(rest, { ...LIST_FILTER_FLAGS, "--name": "name" }, FILTER_BOOL_FLAGS);
     const name = String(args.name || "").trim();
     if (!name) die('usage: argorant lists create --name "My list" [filters]   (e.g. --title CEO --country Germany)');
-    const filters = {};
-    for (const field of Object.values(LIST_FILTER_FLAGS)) if (args[field]) filters[field] = args[field];
-    for (const field of ["has_phone", "has_linkedin", "has_email"]) if (args[field]) filters[field] = "true";
+    const filters = collectFilters(args, LIST_FILTER_FLAGS);
     if (args._.length) filters.q = args._.join(" ");
     if (!Object.keys(filters).length) die("give at least one filter, for example --title CEO --country Germany");
     const body = { name, filters };
     const r = need(await request("POST", args.base, `${V1}/lists`, { key, body }), "lists create");
     if (args.json) return console.log(JSON.stringify(r, null, 2));
     const l = r.list && typeof r.list === "object" ? r.list : r;
-    console.log(green("✓") + ` Saved list ${bold("#" + (l.list_id ?? l.id))} ${dim("“" + (l.name || name) + "”")} · ${bold(Number(l.snapshot_total || 0).toLocaleString())} matching people`);
-    console.log(dim(`Export it:  argorant lists export ${l.list_id ?? l.id} -n 500 -o leads.csv`));
+    const lid = l.list_id ?? l.id;
+    const fill = await listFill(args.base, key, lid, r);
+    if (fill && fill.filling) {
+      console.log(green("✓") + ` Saved list ${bold("#" + lid)} ${dim("“" + (l.name || name) + "”")}`);
+      console.log(`  ${fillLine(fill)}`);
+      console.log(dim(`Check it:  argorant lists show ${lid}`));
+      return;
+    }
+    console.log(green("✓") + ` Saved list ${bold("#" + lid)} ${dim("“" + (l.name || name) + "”")} · ${bold(Number(l.snapshot_total || 0).toLocaleString())} matching people`);
+    console.log(dim(`Export it:  argorant lists export ${lid} -n 500 -o leads.csv`));
+    return;
+  }
+  if (sub === "add") {
+    const args = readFlags(rest, LIST_FILTER_FLAGS, FILTER_BOOL_FLAGS);
+    const id = numericId(args._[0], "list id", "usage: argorant lists add <id> [filters]   (adds every match; people already in the list are skipped)");
+    const filters = collectFilters(args, LIST_FILTER_FLAGS);
+    if (args._.length > 1) filters.q = args._.slice(1).join(" ");
+    if (!Object.keys(filters).length) die("give at least one filter, for example --title CEO --country Germany");
+    const r = need(await request("POST", args.base, `${V1}/lists/${id}/items`, { key, body: { filters } }), "lists add");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    if (r.summary) console.log(green("✓") + " " + r.summary);
+    else console.log(green("✓") + ` Added ${Number(r.added || 0).toLocaleString()} people to list #${id}`);
+    const fill = await listFill(args.base, key, id, r);
+    if (fill && fill.filling) console.log(`  ${fillLine(fill)}`);
     return;
   }
   if (sub === "show" || sub === "get" || sub === "status") {
@@ -3267,7 +3342,14 @@ async function cmdLists(argv) {
     const r = need(await request("GET", args.base, `${V1}/lists/${id}`, { key }), "list");
     if (args.json) return console.log(JSON.stringify(r, null, 2));
     const l = r.list && typeof r.list === "object" ? r.list : r;
-    console.log(listLine(l));
+    const fill = await listFill(args.base, key, id, null);
+    if (fill && fill.filling) {
+      console.log(`${bold("#" + (l.list_id ?? l.id ?? id))}  ${l.name || "-"}`);
+      console.log(`  ${fillLine(fill)}`);
+    } else {
+      console.log(listLine(l));
+      if (fill && fill.fill && fill.fill.status === "failed") console.log(`  ${fillLine(fill)}`);
+    }
     const f = l.filters && typeof l.filters === "object" ? Object.entries(l.filters).filter(([k, v]) => v && k !== "record_type") : [];
     if (f.length) console.log(dim(`  filters: ${f.map(([k, v]) => `${k}=${v}`).join(", ")}`));
     console.log(dim(`  argorant lists people ${id}   ·   argorant lists export ${id} -o leads.csv`));
@@ -3308,7 +3390,34 @@ async function cmdLists(argv) {
     return console.log(green("✓") + ` Deleted list #${id}`);
   }
   if (sub === "export") return listsExport(rest, key);
-  die(`unknown lists subcommand: ${sub} (ls, create, show, people, rename, rm, export)`);
+  die(`unknown lists subcommand: ${sub} (ls, create, add, show, people, rename, rm, export)`);
+}
+
+// A list that is still filling (saved from a search, or grown with `lists add`) is never reported as
+// complete: GET /api/v1/lists/{id}/fill says how far it is. Null when the API has no fill status.
+async function listFill(base, key, id, created) {
+  // After a save or an add: only when the answer says it is still filling (queued or processing).
+  if (created && !created.async && !(created.materialize && ["queued", "processing"].includes(created.materialize.status))) return null;
+  let res;
+  try {
+    res = await request("GET", base, `${V1}/lists/${encodeURIComponent(String(id))}/fill`, { key });
+  } catch {
+    return null;
+  }
+  if (res.status >= 400 || !res.json) return null;
+  return res.json;
+}
+function fillLine(fill) {
+  const job = (fill && fill.fill) || {};
+  const list = (fill && fill.list) || {};
+  const sofar = Math.max(Number(job.inserted_rows || 0), Number(list.item_count || 0));
+  if (job.status === "processing") return `filling: ${sofar.toLocaleString()} people so far${job.target_rows ? ` of about ${Number(job.target_rows).toLocaleString()}` : ""}`;
+  if (job.status === "queued") {
+    const ahead = Number(job.queue_position || 0);
+    return `waiting for its turn${ahead ? ` (${ahead} before it)` : ""}; ${Number(list.item_count || 0).toLocaleString()} people in it now`;
+  }
+  if (job.status === "failed") return `the last fill did not finish; ${Number(list.item_count || 0).toLocaleString()} people in it. Save or add the search again.`;
+  return `ready with ${Number(list.item_count || list.snapshot_total || 0).toLocaleString()} people`;
 }
 
 async function listsExport(rest, key) {
@@ -3434,8 +3543,9 @@ async function cmdCredits(argv) {
     return console.log(`
 ${bold("argorant credits")} packs                      ${dim("the credit packs and their prices")}
 ${bold("argorant credits")} quote <credits>            ${dim("a price quote for one pack; nothing is bought")}
-${bold("argorant credits")} buy <credits> [--pay-with link] [--yes]
-    ${dim("shows the quote, asks, then charges the saved card (when your workspace allows it) or gives you a payment link")}
+${bold("argorant credits")} buy <credits> [--pay-with link] [--yes] [--confirmation "<the user's yes>"]
+    ${dim("shows the quote, asks, then charges the saved card (when the account owner allowed it, up to a monthly limit) or gives you a payment link")}
+    ${dim("every purchase records its confirmation: your answer at the prompt, or the words passed with --confirmation")}
 ${bold("argorant credits")} purchases [<id>]           ${dim("purchases made with this account")}
 ${dim("1 credit = 1 valid contact; 0.5 credit = 1 email check. Bought credits stay valid for 365 days.")}
 `);
@@ -3452,7 +3562,7 @@ ${dim("1 credit = 1 valid contact; 0.5 credit = 1 email check. Bought credits st
     return;
   }
   if (sub === "quote" || sub === "buy") {
-    const args = readFlags(rest, { "--currency": "currency", "--pay-with": "payWith" });
+    const args = readFlags(rest, { "--currency": "currency", "--pay-with": "payWith", "--confirmation": "confirmation" });
     const credits = parseLimit(String(args._[0] || "").replace(/[,_]/g, "") || "x", "credits");
     const body = { credits };
     if (args.currency) body.currency = String(args.currency).toLowerCase();
@@ -3468,9 +3578,14 @@ ${dim("1 credit = 1 valid contact; 0.5 credit = 1 email check. Bought credits st
     if (!args.json) for (const l of quoteLines(q)) console.log(l);
     const card = q.payment && q.payment.saved_card;
     const how = payWith !== "link" && card && card.usable ? `The saved ${card.card || "card"} is charged now.` : "You get a payment link; nothing is charged before you pay it.";
-    if (!(await confirmOrDie(args, `Buy ${credits.toLocaleString()} credits for ${fmtPrice(q.price_cents !== undefined || q.amount_cents !== undefined ? q : q.pack || q, q.currency)}? ${how}`, "Buying credits needs a confirmation."))) return;
+    const question = `Buy ${credits.toLocaleString()} credits for ${fmtPrice(q.price_cents !== undefined || q.amount_cents !== undefined ? q : q.pack || q, q.currency)}? ${how}`;
+    if (!(await confirmOrDie(args, question, "Buying credits needs a confirmation."))) return;
     const pbody = { quote_id: q.quote_id, confirmed: true };
     if (payWith !== "auto") pbody.pay_with = payWith;
+    // The purchase records how it was confirmed (2026-10-07): the user's own words when an agent passes them,
+    // the answer at the prompt, or nothing extra with --yes (the record then says confirmed=true).
+    const said = args.confirmation ? String(args.confirmation) : !args.yes ? `Answered yes at the terminal to: ${question}` : "";
+    if (said.trim()) pbody.user_confirmation = said.replace(/\s+/g, " ").trim().slice(0, 1000);
     const r = need(await request("POST", args.base, `${V1}/credits/purchases`, { key, body: pbody }), "credit purchase");
     if (args.json) return console.log(JSON.stringify({ quote: q, purchase: r }, null, 2));
     const p = r.purchase && typeof r.purchase === "object" ? { ...r.purchase, ...r } : r;
@@ -3617,7 +3732,9 @@ async function cmdCompanies(argv) {
 ${bold("argorant companies")} count [filters]                         ${dim("free")}
 ${bold("argorant companies")} search [filters] [-n 25] [--cursor <c>] [--all]   ${dim("free")}
 ${bold("argorant companies")} people <company.com> [--title <role>] [-n 5]      ${dim("free; same as argorant company")}
-  filters: --industry --country --state --city --company --domain --keywords --technologies --employees 11-50,51-200 [free text]
+  filters: --industry --country --state --city --domain (each with --exclude-...) --company --keywords
+           --exclude-keywords --keyword-scope --technologies --employees 11-50,51-200 --employees-min/max
+           --revenue --revenue-min/max --near <place> --radius <n> [free text]
 `);
   }
   const key = requireKey();
@@ -3651,12 +3768,48 @@ ${bold("argorant companies")} people <company.com> [--title <role>] [-n 5]
 }
 
 function companyFilters(args) {
-  const q = {};
-  for (const field of new Set(Object.values(COMPANY_FILTER_FLAGS))) if (args[field]) q[field] = args[field];
+  const q = collectFilters(args, COMPANY_FILTER_FLAGS, {});
   if (args._.length) q.q = [q.q, ...args._].filter(Boolean).join(" ");
+  if (q.radius !== undefined && !q.radius_target) q.radius_target = "company";
   return q;
 }
 
+// ---- filters: every filter, its values, and whether it can be used now ----
+async function cmdFilters(args) {
+  const key = resolveKey();
+  let schema = null;
+  let live = false;
+  if (key) {
+    try {
+      const res = await request("GET", args.base, "/api/v1/people/filters", { key });
+      if (res.status < 400 && res.json && Array.isArray(res.json.filters)) {
+        schema = res.json;
+        live = true;
+      } else if (res.status === 401) need(res, "filters");
+    } catch {
+      /* offline: the bundled list below */
+    }
+  }
+  if (!schema) schema = FILTER_SCHEMA;
+  if (args.json) return console.log(JSON.stringify(schema, null, 2));
+  const flags = schema.cli_flags || FILTER_SCHEMA.cli_flags || {};
+  console.log(bold("Filters") + dim(live ? "  (ready now, from your account)" : "  (bundled list; log in to see what is ready now)"));
+  for (const f of schema.filters || []) {
+    const names = [f.include, f.exclude, ...(f.kind === "range" || f.kind === "radius" ? f.params : [])]
+      .filter(Boolean)
+      .filter((p, i, a) => a.indexOf(p) === i)
+      .map((p) => flags[p] || `--${p.replace(/_/g, "-")}`);
+    const state = !live ? "" : f.ready ? green("  ready") : red("  not ready yet") + dim(f.reason ? `  ${f.reason}` : "");
+    console.log(`  ${bold(f.label)}  ${dim(names.join(" "))}${state}`);
+    if (Array.isArray(f.values) && f.values.length) console.log(dim(`      values: ${f.values.map((v) => v.value).join(", ")}`));
+  }
+  for (const [name, m] of Object.entries(schema.modes || {})) {
+    console.log(`  ${bold(m.label)}  ${dim(flags[name] || "--" + name.replace(/_/g, "-"))}`);
+    console.log(dim(`      values: ${(m.values || []).map((v) => v.value).join(", ")}${m.default ? `  (default ${m.default})` : ""}`));
+  }
+  console.log(dim("  Every list filter takes several values; a comma means any of them. Include and exclude work together."));
+}
+
 // ---- lookup ----
 async function cmdLookup(argv) {
   const raw = String(argv[0] || "").toLowerCase();
@@ -3712,7 +3865,8 @@ ${bold("COMMANDS")}
   ${cyan("export status")} <job_id>     Status of an existing export  ${dim("(free; add --batch for >50k)")}
   ${cyan("export download")} <job_id> -o leads.csv   Re-download a finished export ${dim("(free)")}
   ${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("list status")} <id>           Show a saved list's size, or how far it has filled ${dim("(free)")}
+  ${cyan("filters")}                    Every filter, its values, and which are ready now ${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)")}
   ${cyan("find")} "<first last>" --domain <d>   Find a person's work email ${dim("(1 credit found, 0.25 credit nothing found)")}
@@ -3726,24 +3880,35 @@ ${bold("COMMANDS")}
   ${cyan("inbox")} list | read | reply | forward | classify   Replies across campaigns; answer in-thread or forward
   ${cyan("blocklist")} list | add | remove       Addresses and domains never contacted
   ${cyan("account")}                    Plan, credits, request limit, campaign emails ${dim("(free)")}
-  ${cyan("lists")} ls | create | show | people | rename | rm | export   Saved lists ${dim("(argorant lists help)")}
+  ${cyan("lists")} ls | create | add | show | people | rename | rm | export   Saved lists ${dim("(argorant lists help)")}
   ${cyan("exports")} ls | status | download    Your exports, a page at a time ${dim("(free)")}
   ${cyan("companies")} count | search | people   Companies that match your filters ${dim("(free)")}
   ${cyan("lookup")} industries | countries | keywords | technologies | titles [text]   Exact filter labels ${dim("(free)")}
   ${cyan("credits")} packs | quote | buy | purchases   Buy credit packs ${dim("(asks first; saved card or payment link)")}
   ${cyan("webhooks")} ls | add | set | test | deliveries | rm   Get events sent to your server ${dim("(Pro plan and up)")}
 
-${bold("FILTERS")}
-  --keywords <k>     Comma = OR. The widest, most reliable filter - prefer it
-                     over --industry (matches tags most records carry).
-  --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          --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…")}
-  ${dim("--exclude-title works fully with `export` and `list create`; `count`/`search`/`reveal` don't apply it yet (CLI warns).")}
+${bold("FILTERS")}  ${dim("(the same on every command: count, search, reveal, export, lists, companies, campaigns)")}
+  Each list filter has an include flag and an exclude flag; use both together.
+  A comma means any of them.
+  --title <t>          --exclude-title <t>        --title-match words|exact|contains
+  --keywords <k>       --exclude-keywords <k>     --keyword-scope company|people|any
+  --industry <i>       --exclude-industry <i>
+  --country <c>        --exclude-country <c>      ${dim("(regions too: Europe, EMEA, DACH, Nordics, APAC, LATAM, GCC)")}
+  --state <s>          --exclude-state <s>        --city <c>   --exclude-city <c>
+  --seniority <s>      --exclude-seniority <s>
+  --department <d>     --exclude-department <d>
+  --domain <d>         --exclude-domain <d>       --company <name>
+  --employees <bands>  --employees-min <n>        --employees-max <n>
+  --revenue <bands>    --revenue-min <usd>        --revenue-max <usd>
+  --near <place or lat,lon> --radius <n> [--radius-unit mi|km] [--radius-target person|company]
+  --gender female|male       --income <bands>     ${dim("(estimates; not for lending audiences)")}
+  --has-phone          --has-linkedin             --has-email          --verified-only
+  ${dim("--title-match words (default): whole words, so Data does not match Database. exact: the whole")}
+  ${dim("job title, so CEO does not match Founder & CEO. contains: anywhere in the title.")}
+  ${dim("--keyword-scope company (default): company tags, industry and description. people: skills and")}
+  ${dim("profile text. any: both, plus job title and company name.")}
+  ${dim("--title is abbreviation-aware (CFO and Chief Financial Officer find each other).")}
+  ${dim("Run `argorant filters` for every value and to see which filters are ready now.")}
 
 ${bold("OPTIONS")}
   -n, --limit <n>    Max rows           -o, --output <file>   CSV path (export)
@@ -3824,7 +3989,7 @@ const OWN_FLAG_COMMANDS = {
   lookup: (a) => cmdLookup(a),
   lookups: (a) => cmdLookup(a),
 };
-const LISTS_SUBCOMMANDS = new Set(["ls", "people", "items", "rename", "rm", "delete", "remove", "export", "show", "get", "help"]);
+const LISTS_SUBCOMMANDS = new Set(["ls", "add", "people", "items", "rename", "rm", "delete", "remove", "export", "show", "get", "help"]);
 
 async function main() {
   const argv = takeIdempotencyFlag(process.argv.slice(2));
@@ -3857,6 +4022,7 @@ async function main() {
     export: cmdExport,
     list: cmdList,
     verify: cmdVerify,
+    filters: cmdFilters,
   };
   const fn = table[cmd];
   if (!fn) die(`unknown command: ${cmd}\nRun \`argorant help\` for usage.`);
@@ -3877,5 +4043,7 @@ if (require.main === module) {
     errorMessage, errorCode, requestIdOf, detailMsg, need, EXIT, request, pageQuery, pickItems, fetchPages, retryWaitSeconds, RATE_RETRY,
     companyFilters, numericId, fmtPrice, packLine, quoteLines, LOOKUP_KINDS, OWN_FLAG_COMMANDS, VERSION,
     parseCsv, mailboxesFromCsv, mailboxBody, normalizeSecurity, SMTP_BULK_CHUNK,
+    FILTER_SCHEMA, FILTER_VALUE_FLAGS, FILTER_BOOL_FLAGS, FILTER_ENUMS, VALUE_FLAGS, BOOL_FLAGS, CAMPAIGN_FILTER_VALUE_FLAGS,
+    LIST_FILTER_FLAGS, COMPANY_FILTER_FLAGS, COMPANY_PARAMS, finishFilters, collectFilters, checkEnum, fillLine,
   };
 }