argorant 0.11.0 → 0.12.0

package/README.md

@@ -34,8 +34,11 @@ CI, and agents.
 | `company <company.com> -n 5` | Count people at a company, split business-email coverage, preview masked roles | free |
 | `search "<query>" -n 10` | Preview matches (masked identity, details redacted) | free |
 | `sample <company.com> [-o sample.csv]` | Read a website and build 25 distinct, live-valid company leads from it | free sample |
-| `reveal "<query>" -n 25` | Reveal full contact details (name, email, phone, LinkedIn) | quota |
-| `export "<query>" -n 1000 -o leads.csv` | Verified CSV export, polled until ready | quota |
+| `reveal "<query>" -n 25` | Reveal full contact details (name, work email, LinkedIn) | 1 credit per new working email |
+| `reveal "<query>" -n 25 --phones` | Same, plus each person's phone number (direct dial or mobile) | + 10 credits per number found |
+| `enrich --email <a@b.com> [--phones]` | The person behind an address, optionally with their phone number | 1 credit per match, + 10 if a number is found |
+| `export "<query>" -n 1000 -o leads.csv` | Verified CSV export, polled until ready | 1 credit per working email |
+| `export "<query>" -n 1000 --phones -o leads.csv` | Same, with phone numbers in the file | + 10 credits per number in the file |
 | `export status <job_id> [--batch]` | Status of an export you already created | free |
 | `export download <job_id> [--batch] -o leads.csv` | Re-download a finished export | free |
 | `list create --name "<n>" [filters]` | Save a reusable filtered list (server counts it) | free |
@@ -45,6 +48,20 @@ CI, and agents.
 | `find status \| download \| resume \| cancel <job_id>`, `find pricing` | Manage a find job; show prices, balance and limits | free |
 | `campaigns …` | Live outbound campaigns - **operator keys only**, see below | - |
 
+## Phone numbers
+
+Phone numbers are never included unless you ask for them with `--phones` (reveal, enrich, export).
+A phone number costs 10 credits, and only when a number is actually returned. People without a number
+cost nothing, and numbers you already unlocked (in the app, the API or the connector) are free. Phone
+numbers come with the Pro plan and higher. The CLI shows the price before it spends anything, and the
+result says per person whether a number came back and what it cost. Company and HQ numbers stay free.
+
+```sh
+npx argorant reveal --title CFO --domain stripe.com -n 5 --phones
+npx argorant enrich --email patrick@stripe.com --phones --json
+npx argorant export --title CFO --country Germany -n 200 --phones -o cfos.csv
+```
+
 Exports above 50,000 rows are created as a multi-chunk batch: the CLI polls
 `export status --batch` for you and writes one file per chunk
 (`leads-part1.csv`, `leads-part2.csv`, …). The batch id is printed so you can

package/bin/argorant.js

@@ -146,7 +146,7 @@ function parseLimit(raw, flag) {
 }
 
 function parseArgs(argv) {
-  const out = { _: [], filters: {}, limit: null, output: null, file: null, column: null, json: false, yes: false, base: DEFAULT_BASE, baseExplicit: false, batch: false, name: null, includeExported: false, grade: "valid", gradeExplicit: false };
+  const out = { _: [], filters: {}, limit: null, output: null, file: null, column: null, json: false, yes: false, base: DEFAULT_BASE, baseExplicit: false, batch: false, name: null, includeExported: false, grade: "valid", gradeExplicit: false, phones: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--json") out.json = true;
@@ -158,6 +158,9 @@ function parseArgs(argv) {
     else if (a === "--base") { out.base = flagValue(argv, i++, a); out.baseExplicit = true; }
     else if (a === "--name") out.name = flagValue(argv, i++, a);
     else if (a === "--include-exported") out.includeExported = true;
+    // Phone numbers are opt-in on every surface (2026-10-07): only with --phones, 10 credits per
+    // number actually returned, nothing when none is found or the account already has it.
+    else if (a === "--phones" || a === "--include-phones") out.phones = true;
     else if (a === "--batch") out.batch = true;
     else if (a === "--grade") setGrade(out, flagValue(argv, i++, a));
     else if (a in VALUE_FLAGS) out.filters[VALUE_FLAGS[a]] = flagValue(argv, i++, a);
@@ -554,22 +557,106 @@ async function cmdSample(args) {
   console.log(dim(`These 25 are the sample; the full pool contains ${Number(job.total_companies || 0).toLocaleString()} companies.`));
 }
 
+// ---- phone numbers (opt-in, --phones) ----
+const PHONE_FIELDS = ["phone", "phone_1", "phone_2", "phones_all", "additional_phones", "phone_masked"];
+function stripPhones(rec) {
+  if (rec && typeof rec === "object") for (const k of PHONE_FIELDS) delete rec[k];
+  return rec;
+}
+
+// The price and whether the plan includes phone numbers, before anything is spent. An older server
+// without the pricing route falls back to the published price.
+async function phonePricing(args, key) {
+  try {
+    const res = await request("GET", args.base, "/api/v1/people/phones/pricing", { key });
+    if (res.status === 200 && res.json) return res.json;
+  } catch {
+    /* fall back below */
+  }
+  return { price_per_phone: 10, plan_includes_phones: null };
+}
+
+function phonePriceText(pricing) {
+  const price = Number((pricing && pricing.price_per_phone) || 10);
+  return `Phone numbers cost ${price} credits each, only when a number is found. Numbers you already have are free.`;
+}
+
+// Phone numbers for people already revealed (POST /api/v1/people/phones). A refusal never undoes the
+// emails that were just revealed: it comes back as {included:false, message}.
+async function addPhones(args, key, records) {
+  const ids = [];
+  for (const r of records) {
+    const id = String(r.person_id || r.record_id || "").trim();
+    if (id && !ids.includes(id)) ids.push(id);
+  }
+  records.forEach(stripPhones);
+  if (!ids.length) return { included: true, phones_returned: 0, credits_charged: 0, summary: "No people to look up phone numbers for, so nothing was charged." };
+  const res = await request("POST", args.base, "/api/v1/people/phones", {
+    key,
+    body: { record_ids: ids.slice(0, 100), channel: "cli" },
+    headers: { "X-Argorant-Channel": "cli" },
+  });
+  if (res.status !== 200 || !res.json) {
+    const detail = res.json && res.json.detail;
+    const code = detail && typeof detail === "object" ? detail.error : null;
+    let message = detailMsg(detail) || `phone numbers failed (HTTP ${res.status}).`;
+    if (code === "phones_not_in_plan") message = "Your plan does not include phone numbers, so none were added and nothing was charged for them.";
+    else if (code === "insufficient_credits") message = "Not enough credits for a phone number, so none were added and nothing was charged for them.";
+    else if (code === "mcp_quota_exceeded") message = "Today's reveal limit is used up, so no phone numbers were added. It resets at midnight UTC.";
+    for (const r of records) r.phone_status = "not_added";
+    return { included: false, status: res.status, error: code || "error", message, summary: message };
+  }
+  const byId = new Map((res.json.results || []).map((row) => [String(row.record_id), row]));
+  for (const r of records) {
+    const row = byId.get(String(r.person_id || r.record_id || "")) || {};
+    r.phone = row.phone || null;
+    if (row.additional_phones && row.additional_phones.length) r.additional_phones = row.additional_phones;
+    r.phone_status = row.phone_status || "not_found";
+    r.phone_credits_charged = Number(row.credits_charged || 0);
+  }
+  return { included: true, ...res.json, results: undefined };
+}
+
+function phoneLine(p) {
+  if (!p || !p.phone_status) return null;
+  if (p.phone) {
+    const extra = p.additional_phones && p.additional_phones.length ? dim(` (+${p.additional_phones.length} more)`) : "";
+    const cost = p.phone_credits_charged ? dim(` · ${p.phone_credits_charged} credits`) : p.phone_status === "already_unlocked" ? dim(" · already yours") : "";
+    return `${p.phone}${extra}${cost}`;
+  }
+  if (p.phone_status === "none_found" || p.phone_status === "not_found") return dim("no phone number on record · not charged");
+  if (p.phone_status === "not_enough_credits") return dim("phone not added · not enough credits");
+  if (p.phone_status === "not_in_plan") return dim("phone not added · not in your plan");
+  if (p.phone_status === "daily_limit_reached") return dim("phone not added · daily limit reached");
+  return null;
+}
+
 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;
+  if (pricing && pricing.plan_includes_phones === false) {
+    warn("Your plan does not include phone numbers. Emails are revealed as usual; no phone numbers will be added or charged.");
+  }
   // Confirmation is interactive-only by design: with --yes, --json, or a
   // non-TTY stdin (CI, agents, pipes) this spends credits with no prompt.
   if (!args.yes && !args.json && process.stdin.isTTY) {
-    const ans = await prompt(`Reveal up to ${bold(limit)} contacts? This uses your quota/credits. [y/N] `);
+    const phonesText = args.phones ? ` ${phonePriceText(pricing)}` : "";
+    const ans = await prompt(`Reveal up to ${bold(limit)} contacts${args.phones ? " with phone numbers" : ""}? Each new working email costs 1 credit.${phonesText} [y/N] `);
     if (!/^y(es)?$/i.test(ans)) return console.log(dim("aborted."));
+  } else if (args.phones && !args.json) {
+    process.stderr.write(dim(phonePriceText(pricing) + "\n"));
   }
   // Sent for forward-compatibility: the platform has no per-request grade
   // control on reveal yet (see GODMODE-PLAN.md), so this is a no-op today.
   const query = { ...args.filters, limit, grade: args.grade === "valid-plus-catchall" ? "valid_plus_catchall" : "valid" };
   const res = await request("GET", args.base, "/api/mcp/people/reveal", { key, query });
   const r = need(res, "reveal");
+  const people = (r.results || []).filter((x) => x && typeof x === "object");
+  if (args.phones && people.length) r.phones = await addPhones(args, key, people);
+  else people.forEach(stripPhones);
   if (args.json) return console.log(JSON.stringify(r, null, 2));
   console.log(dim(`${Number(r.total).toLocaleString()} total · revealed ${r.returned}`));
   for (const p of r.results || []) {
@@ -578,8 +665,16 @@ async function cmdReveal(args) {
     const name = p.full_name || [p.first_name, p.last_name].filter(Boolean).join(" ") || p.name;
     const who = [name, p.title].filter(Boolean).join(" · ");
     console.log(`  ${bold(who || "-")}`);
-    const bits = [p.email && cyan(p.email), p.phone, p.linkedin_url, [p.company || p.company_name, p.country].filter(Boolean).join(", ")].filter(Boolean);
+    const bits = [p.email && cyan(p.email), p.linkedin_url, [p.company || p.company_name, p.country].filter(Boolean).join(", ")].filter(Boolean);
     if (bits.length) console.log("    " + bits.join(dim(" · ")));
+    const phone = args.phones ? phoneLine(p) : null;
+    if (phone) console.log("    " + phone);
+  }
+  const charged = Number(r.charged || 0);
+  console.log(dim(`${charged} credit${charged === 1 ? "" : "s"} charged for emails`));
+  if (r.phones) {
+    if (r.phones.included) console.log(dim(r.phones.summary || `${r.phones.credits_charged || 0} credits charged for phone numbers`));
+    else warn(r.phones.message || "No phone numbers were added.");
   }
 }
 
@@ -622,16 +717,30 @@ async function cmdEnrich(args) {
   else if (name) { body.name = name; body.domain = domain; }
   else body.domain = domain;
   const personMode = Boolean(body.email || body.name);
+  if (args.phones && !personMode) warn("Phone numbers are for people. A company lookup returns the company profile only.");
+  const wantPhones = args.phones && personMode;
+  const pricing = wantPhones ? await phonePricing(args, key) : null;
+  if (pricing && pricing.plan_includes_phones === false) {
+    warn("Your plan does not include phone numbers. The email lookup runs as usual; no phone number will be added or charged.");
+  }
   // Company mode is free, so it never asks. Person mode is billed exactly like
   // a reveal, so it gets the same interactive-only confirmation as `reveal`.
   if (personMode && !args.yes && !args.json && process.stdin.isTTY) {
     const ans = await prompt(
-      `Enrich this contact? A match costs 1 credit; a miss and a non-deliverable address are free. [y/N] `
+      `Enrich this contact? A match costs 1 credit; a miss and a non-deliverable address are free.` +
+        (wantPhones ? ` ${phonePriceText(pricing)}` : "") + ` [y/N] `
     );
     if (!/^y(es)?$/i.test(ans)) return console.log(dim("aborted."));
+  } else if (wantPhones && !args.json) {
+    process.stderr.write(dim(phonePriceText(pricing) + "\n"));
   }
   const res = await request("POST", args.base, "/api/v1/enrich", { key, body });
   const r = need(res, "enrich");
+  if (r && r.type === "person" && r.person && typeof r.person === "object") {
+    if (!r.person.person_id && r.person_id) r.person.person_id = r.person_id;
+    if (wantPhones && r.found) r.phones = await addPhones(args, key, [r.person]);
+    else stripPhones(r.person);
+  }
   if (args.json) {
     console.log(JSON.stringify(r, null, 2));
     if (!r.found) process.exit(EXIT.ERROR);
@@ -656,11 +765,13 @@ async function cmdEnrich(args) {
   console.log(`  ${bold(who || "-")}`);
   const bits = [
     p.email && cyan(p.email),
-    p.phone,
     p.linkedin_url,
     [p.current_company_name, p.current_company_domain, p.country].filter(Boolean).join(", "),
   ].filter(Boolean);
   if (bits.length) console.log("    " + bits.join(dim(" · ")));
+  const phone = wantPhones ? phoneLine(p) : null;
+  if (phone) console.log("    " + phone);
+  if (r.phones && !r.phones.included) warn(r.phones.message || "No phone number was added.");
   if (r.deliverable === false) {
     console.log("    " + dim(r.message || "This address did not pass live verification, so nothing was charged."));
   }
@@ -791,9 +902,18 @@ async function cmdExport(args) {
   const dest = ensureWritable(args.output || "argorant-leads.csv");
   // Confirmation is interactive-only by design: with --yes, --json, or a
   // non-TTY stdin (CI, agents, pipes) this spends credits with no prompt.
+  const pricing = args.phones ? await phonePricing(args, key) : null;
+  if (pricing && pricing.plan_includes_phones === false) {
+    die("Your plan does not include phone numbers. Run the export without --phones.", EXIT.UPGRADE);
+  }
   if (!args.yes && !args.json && process.stdin.isTTY) {
-    const ans = await prompt(`Export up to ${bold(limit)} verified contacts to ${bold(dest)}? Uses quota/credits. [y/N] `);
+    const phonesText = args.phones
+      ? ` Phone numbers are included. Each number in the file costs ${Number((pricing && pricing.price_per_phone) || 10)} more credits, and people without one cost nothing extra.`
+      : "";
+    const ans = await prompt(`Export up to ${bold(limit)} verified contacts to ${bold(dest)}? Each person with a working email costs 1 credit.${phonesText} [y/N] `);
     if (!/^y(es)?$/i.test(ans)) return console.log(dim("aborted."));
+  } else if (args.phones && !args.json) {
+    process.stderr.write(dim(`Phone numbers are included. Each number in the file costs ${Number((pricing && pricing.price_per_phone) || 10)} more credits.\n`));
   }
   // Match the MCP/app defaults so the CLI yields the same rows: business email
   // present by default, and skip rows already exported (override with
@@ -808,7 +928,7 @@ async function cmdExport(args) {
   const grades = args.grade === "valid-plus-catchall" ? ["valid", "catch_all"] : ["valid"];
   const create = await request("POST", args.base, "/api/mcp/exports/create", {
     key,
-    body: { limit, filters: exportFilters, exclude_previously_exported: !args.includeExported, grades },
+    body: { limit, filters: exportFilters, exclude_previously_exported: !args.includeExported, grades, ...(args.phones ? { include_phones: true } : {}) },
   });
   const job = need(create, "export");
   // >EXPORT_MAX_ROWS (50k) → a multi-chunk batch, a different status endpoint
@@ -2386,10 +2506,13 @@ ${bold("COMMANDS")}
   ${cyan("search")} "<query>" -n 10     Preview matches, details redacted ${dim("(0 contact credits)")}
   ${cyan("sample")} <company.com>        Build 25 distinct, live-valid company leads ${dim("(free sample)")}
   ${cyan("reveal")} "<query>" -n 25     Reveal full contact details    ${dim("(uses credits; live-verified, pay only for deliverable)")}
+  ${cyan("reveal")} ... --phones         Also add phone numbers         ${dim("(10 credits per number found; none found = free)")}
   ${cyan("enrich")} --email <a@b.com>   One address → the full person profile ${dim("(1 credit per match; miss = free)")}
   ${cyan("enrich")} --name "<n>" --domain <d>   Find that person + reveal a verified email ${dim("(1 credit per match)")}
   ${cyan("enrich")} --domain <d>        Company profile                ${dim("(0 contact credits)")}
+  ${cyan("enrich")} ... --phones         Also add the person's phone number ${dim("(10 credits if found)")}
   ${cyan("export")} "<query>" -n 1000 -o leads.csv   Verified CSV export ${dim("(uses credits)")}
+  ${cyan("export")} ... --phones         Include phone numbers in the file ${dim("(10 credits per number in the file)")}
   ${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)")}
@@ -2424,6 +2547,9 @@ ${bold("OPTIONS")}
       --json         Raw JSON output    -y, --yes             Skip confirmations
       --base <url>   Override API base  (or ARGORANT_API_BASE)
       --batch        Treat the id in \`export status/download\` as a batch id
+      --phones       Include phone numbers (reveal, enrich, export). Off by default.
+                     10 credits per phone number returned, nothing if none is found;
+                     numbers you already unlocked are free. From the Pro plan.
       --max-credits <n>  Credit cap for a \`find --file\` job (it pauses at the cap)
       --grade <g>    valid (default) or valid-plus-catchall - which deliverable
                      grade to include on reveal/export. You only ever pay for
@@ -2451,6 +2577,8 @@ ${bold("EXAMPLES")}
   ${p} enrich --email patrick@stripe.com --json
   ${p} enrich --name "Patrick Collison" --domain stripe.com
   ${p} enrich --domain stripe.com
+  ${p} reveal --title CFO --domain stripe.com -n 5 --phones
+  ${p} export --title CFO --country Germany -n 200 --phones -o cfos.csv
   ${p} verify ceo@stripe.com
   ${p} verify --file my-list.csv -o verified.csv
   ${p} find "Patrick Collison" --domain stripe.com

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argorant",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Search, count, reveal, export, and verify B2B contacts from the Argorant database, and find work emails by name and company domain, from your terminal, scripts, or coding agent.",
   "bin": {
     "argorant": "bin/argorant.js"