salesprompter-cli 0.1.73 → 0.1.74

package/README.md

@@ -38,6 +38,37 @@ For headless or automation use, generate a CLI token in the app and run `salespr
 
 ## What it does
 
+### Contacts at a named list of companies
+
+`leads:at-companies` researches Director, Head-of, VP and C-level contacts across functions. It exports a shortlist for review without starting email enrichment or outreach.
+
+Create a JSON brief with verified numeric LinkedIn company IDs. Use each subsidiary's own ID; names alone are not an employer match. Missing IDs stay in the coverage report as unresolved.
+
+```json
+{
+  "companies": [
+    { "name": "Your target company", "companyId": "123", "maxContacts": 20 },
+    { "name": "Company awaiting identity review", "maxContacts": 10 }
+  ],
+  "candidatesPerDepartment": 50
+}
+```
+
+```bash
+salesprompter leads:at-companies --brief companies.json --dry-run
+salesprompter leads:at-companies --brief companies.json --out-dir ./company-research
+# Repeat to resume the next batch; completed searches are reused.
+salesprompter leads:at-companies --brief companies.json --out-dir ./company-research
+```
+
+The default six functions are Digital Marketing & CRM, Digital Product & UX, Software Development, IT, Data & AI, and HR. Override them with `departments: [{ "name": "Security", "terms": ["security", "ciso"] }]`. Optional `regionIds` applies explicit Sales Navigator geography filters; no country is inferred from a company name or headquarters.
+
+Contacts must match the current company ID, a senior title and the requested function. Selection alternates between functions, deduplicates profile URLs and never pads a company to its ceiling. The default ceiling is 20; each company can override it. Head-of roles classified as experienced managers are searched, but generic manager titles do not pass the final seniority check.
+
+Outputs are private local `contacts.csv`, `coverage.json` (including rejected/unresolved matches and per-function counts), and `checkpoint.json`. A completed search batch is not exhaustive coverage: each function collects at most `candidatesPerDepartment` candidates and the report records LinkedIn's reported total and any shortfall. Default `--max-searches 12` bounds each invocation. Increase it explicitly for larger batches. HTTP 429/999 stops the run and preserves completed searches; resume after cooldown. An interrupted individual search may be repeated.
+
+Live research requires Salesprompter workspace login and a LinkedIn session. `--browser-relay-port` uses the existing signed-in browser relay. Checkpoints are bound to both the brief and workspace; changed criteria require a new output directory. A concurrent run is refused; after a crash, remove only `.research-lock` after confirming the process stopped. This command does not import the shortlist into the workspace, find emails, or create campaigns. Review company identity, role fit and coverage before downstream use.
+
 - guided setup and auth
 - product and market discovery
 - Sales Navigator search orchestration

package/dist/cli.js

@@ -15,6 +15,7 @@ import pg from "pg";
 import { Command } from "commander";
 import { z } from "zod";
 import { AffiliateCopyReviewSchema, renderAffiliateCopyReview } from "./affiliate-copy.js";
+import { CompanyBriefSchema, planCompanySearches, runCompanyResearch } from "./company-leads.js";
 import { clearAuthSession, loginWithBrowserConnect, loginWithDeviceFlow, loginWithToken, readAuthSession, requireAuthSession, shouldBypassAuth, verifySession, writeAuthSession } from "./auth.js";
 import { buildBigQueryLeadLookupSql, executeBigQuerySql, normalizeBigQueryLeadRows, runBigQueryQuery, runBigQueryRows } from "./bigquery.js";
 import { AccountProfileSchema, EnrichedLeadSchema, IcpSchema, LeadSchema, ScoredLeadSchema, SyncTargetSchema } from "./domain.js";
@@ -706,6 +707,7 @@ const cliPacks = [
         commands: [
             "leads:discover",
             "leads:collect",
+            "leads:at-companies",
             "leads:download",
             "leads:enrich-import",
             "search:run",
@@ -776,6 +778,7 @@ const helpVisibleCommandNames = new Set([
     "auth:whoami",
     "llm:ready",
     "leads:download",
+    "leads:at-companies",
     "contacts:find-linkedin-urls",
     "companies:find-linkedin-urls",
     "contacts:process-emails",
@@ -15131,6 +15134,52 @@ program
     .action(async (options) => {
     printOutput(await runSalesNavigatorPeopleCollectCommand(options));
 });
+program
+    .command("leads:at-companies")
+    .description("Find senior contacts at named companies, balanced across functions; export a review shortlist.")
+    .requiredOption("--brief <path>", "JSON company list with verified company IDs and optional role criteria")
+    .option("--out-dir <path>", "Private output directory and resume checkpoint", "./company-leads")
+    .option("--max-searches <number>", "Maximum company/function searches this invocation", "12")
+    .option("--browser-relay-port <number>", "Use the signed-in Codex browser through a loopback relay")
+    .option("--dry-run", "Preview targeting and unresolved companies without network calls", false)
+    .action(async (options) => {
+    const brief = await readJsonFile(path.resolve(options.brief), CompanyBriefSchema);
+    const jobs = planCompanySearches(brief);
+    const maxSearches = z.coerce.number().int().min(1).max(10000).parse(options.maxSearches);
+    if (options.dryRun) {
+        printOutput({ status: "ok", dryRun: true, searches: jobs, unresolvedCompanies: brief.companies.filter(c => !c.companyId), maxSearches, outreachStarted: false, emailEnrichmentStarted: false });
+        return;
+    }
+    const session = await requireAuthSession();
+    const orgId = session.user.orgId;
+    if (!orgId)
+        throw new Error("Choose a Salesprompter workspace before company research.");
+    const port = options.browserRelayPort == null ? null : z.coerce.number().int().min(1).max(65535).parse(options.browserRelayPort);
+    const relay = port == null ? null : await createLocalAccountSearchBrowserRelay(port);
+    const config = relay ? null : await readLinkedInDirectLookupConfig();
+    let startedSearches = 0;
+    try {
+        const report = await runCompanyResearch({ brief, outDir: path.resolve(options.outDir), scope: `${session.apiBaseUrl}:${orgId}`, maxSearches,
+            search: async (job) => {
+                if (startedSearches++ > 0)
+                    await delay(randomIntegerBetween(5000, 8000));
+                process.stderr.write(`Researching ${job.company.name} — ${job.department.name}\n`);
+                const request = relay
+                    ? { url: buildSalesNavigatorLeadApiUrlFromSearchUrl(job.queryUrl, 100), headers: {} }
+                    : buildSalesNavigatorApiRequestFromSearchUrl(job.queryUrl, config, 100);
+                return fetchAllLocalSalesNavigatorPeople(request, {
+                    requestedProfiles: brief.candidatesPerDepartment, pageSize: 100, pageDelayMinMs: 5000, pageDelayMaxMs: 8000,
+                    retry: { maxRetries: 2, retryBaseDelayMs: 2000, retryMaxDelayMs: 10000 },
+                    executeRequest: relay ? request => relay.request(request) : undefined,
+                });
+            },
+        });
+        printOutput({ status: report.status, selected: report.selected.length, completedSearches: report.completedSearches, totalSearches: report.totalSearches, coverage: report.coverage, output: report.output, resumable: true, outreachStarted: false, emailEnrichmentStarted: false });
+    }
+    finally {
+        await relay?.close();
+    }
+});
 program
     .command("leads:download")
     .alias("leads:export-csv")

package/dist/company-leads.js

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile, chmod, rmdir } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { buildSalesNavigatorPeopleSearchUrl } from "./sales-navigator.js";
+export const defaultDepartments = [
+    { name: "Digital Marketing & CRM", terms: ["marketing", "crm", "growth"] },
+    { name: "Digital Product & UX", terms: ["product", "ux", "design"] },
+    { name: "Software Development", terms: ["software", "engineering", "development", "cto"] },
+    { name: "IT", terms: ["it", "information technology", "cio"] },
+    { name: "Data & AI", terms: ["data", "ai", "artificial intelligence", "analytics"] },
+    { name: "HR", terms: ["hr", "human resources", "people", "personal", "chro"] },
+];
+const companySchema = z.object({
+    name: z.string().trim().min(1),
+    companyId: z.string().regex(/^[1-9]\d*$/).optional(),
+    maxContacts: z.number().int().min(1).max(100).default(20),
+}).strict();
+export const CompanyBriefSchema = z.object({
+    companies: z.array(companySchema).min(1),
+    departments: z.array(z.object({ name: z.string().trim().min(1), terms: z.array(z.string().trim().min(1)).min(1) }).strict()).min(1).default(defaultDepartments),
+    regionIds: z.array(z.string().regex(/^[1-9]\d*$/)).default([]),
+    candidatesPerDepartment: z.number().int().min(1).max(100).default(50),
+}).strict().superRefine((brief, ctx) => {
+    const ids = brief.companies.flatMap(c => c.companyId ? [c.companyId] : []);
+    if (new Set(ids).size !== ids.length)
+        ctx.addIssue({ code: "custom", message: "Duplicate company IDs: merge aliases into one target company." });
+    const names = brief.departments.map(d => d.name.toLowerCase());
+    if (new Set(names).size !== names.length)
+        ctx.addIssue({ code: "custom", message: "Department names must be unique." });
+});
+export function planCompanySearches(brief) {
+    return brief.companies.filter(c => c.companyId).flatMap(company => brief.departments.map((department, index) => ({
+        key: `${company.companyId}:${index}`, company, department,
+        queryUrl: buildSalesNavigatorPeopleSearchUrl([
+            { type: "CURRENT_COMPANY", values: [{ id: company.companyId, text: company.name, selectionType: "INCLUDED" }] },
+            { type: "CURRENT_TITLE", values: department.terms.map(term => ({ text: term, selectionType: "INCLUDED" })) },
+            { type: "SENIORITY_LEVEL", values: [{ id: "310", text: "CXO" }, { id: "300", text: "Vice President" }, { id: "220", text: "Director" }, { id: "210", text: "Experienced Manager" }].map(v => ({ ...v, selectionType: "INCLUDED" })) },
+            ...(brief.regionIds.length ? [{ type: "REGION", values: brief.regionIds.map(id => ({ id, text: id, selectionType: "INCLUDED" })) }] : []),
+        ]),
+    })));
+}
+function words(text) { return text.toLowerCase().normalize("NFKC").replace(/[^\p{L}\p{N}]+/gu, " ").trim(); }
+function hasTerm(title, term) { return ` ${words(title)} `.includes(` ${words(term)} `); }
+function senior(title) {
+    return /\b(director|head|chief|ceo|cto|cio|cdo|cmo|chro|cpo|vp|vice president|vorstand|geschäftsführ\w*|leiter\w*|leitung)\b/i.test(title)
+        && !/\b(assistant|assistent\w*|assistenz|deputy|stellvertret\w*|former|ehemalig\w*)\b/i.test(title);
+}
+function seniorRank(title) {
+    if (/\b(chief|ceo|cto|cio|cdo|cmo|chro|cpo|vorstand|geschäftsführ\w*)\b/i.test(title))
+        return 0;
+    if (/\b(vp|vice president|head|leiter\w*|leitung)\b/i.test(title))
+        return 1;
+    return 2;
+}
+export function canonicalProfile(value) {
+    try {
+        const u = new URL(value);
+        if (!/(^|\.)linkedin\.com$/i.test(u.hostname) || !/^\/(in|sales\/lead)\/[^/]+/.test(u.pathname))
+            return null;
+        return `https://www.linkedin.com${u.pathname.replace(/\/$/, "")}`;
+    }
+    catch {
+        return null;
+    }
+}
+export function shortlistCompanyLeads(brief, results) {
+    const selected = [];
+    const rejected = [];
+    const coverage = [];
+    const seen = new Set();
+    for (const company of brief.companies) {
+        const jobs = planCompanySearches({ ...brief, companies: [company] });
+        const buckets = jobs.map(job => {
+            const rows = [];
+            for (const p of results[job.key]?.people ?? []) {
+                const profile = canonicalProfile(p.profileUrl);
+                // Prefer the actual current job over a free-form profile headline.
+                const raw = p.rawLocalSalesNavigatorResult;
+                const position = raw?.currentPositions?.find(x => String(x.companyId ?? x.companyUrn?.split(":").pop() ?? "") === company.companyId);
+                const title = String(position?.title ?? p.title ?? "");
+                const exactCompany = String(p.companyId ?? "") === company.companyId || Boolean(position);
+                const reason = !profile ? "invalid_profile" : !exactCompany ? "company_not_verified" : !senior(title) ? "seniority_not_verified" : !job.department.terms.some(term => hasTerm(title, term)) ? "function_not_verified" : null;
+                if (reason) {
+                    rejected.push({ companyId: company.companyId, profileUrl: p.profileUrl, reason });
+                    continue;
+                }
+                rows.push({ profileUrl: profile, fullName: p.fullName ?? "", title, companyId: company.companyId, companyName: company.name, department: job.department.name, location: p.location ?? "", sourceQueryUrl: job.queryUrl, observedAt: p.timestamp ?? "" });
+            }
+            return rows.sort((a, b) => seniorRank(String(a.title)) - seniorRank(String(b.title)) || String(a.profileUrl).localeCompare(String(b.profileUrl)));
+        });
+        const local = [];
+        // Round-robin selection stops one function consuming the entire company allowance.
+        while (local.length < company.maxContacts && buckets.some(b => b.length)) {
+            for (const bucket of buckets) {
+                let row;
+                while ((row = bucket.shift())) {
+                    const key = String(row.profileUrl);
+                    if (!seen.has(key)) {
+                        seen.add(key);
+                        local.push(row);
+                        break;
+                    }
+                }
+                if (local.length >= company.maxContacts)
+                    break;
+            }
+        }
+        selected.push(...local);
+        coverage.push({ companyName: company.name, companyId: company.companyId ?? null, selected: local.length, ceiling: company.maxContacts,
+            status: !company.companyId ? "unresolved_company" : jobs.some(j => !results[j.key]) ? "pending" : local.length ? "review_ready" : "no_verified_matches",
+            departments: jobs.map(j => ({ name: j.department.name, selected: local.filter(p => p.department === j.department.name).length, collected: results[j.key]?.people.length ?? null, reported: results[j.key]?.totalResults ?? null, searchComplete: results[j.key]?.totalResults != null ? results[j.key].people.length >= results[j.key].totalResults : null })) });
+    }
+    return { selected, rejected, coverage, outreachStarted: false, emailEnrichmentStarted: false };
+}
+export function companyLeadCsv(rows) {
+    const columns = ["companyName", "companyId", "fullName", "title", "department", "profileUrl", "location", "sourceQueryUrl", "observedAt"];
+    const escape = (value) => { let s = String(value ?? ""); if (/^[=+@\-\t\r]/.test(s))
+        s = "'" + s; return `"${s.replace(/"/g, '""')}"`; };
+    return [columns.join(","), ...rows.map(r => columns.map(c => escape(r[c])).join(","))].join("\n") + "\n";
+}
+export async function runCompanyResearch(input) {
+    await mkdir(input.outDir, { recursive: true, mode: 0o700 });
+    const lock = path.join(input.outDir, ".research-lock");
+    try {
+        await mkdir(lock, { mode: 0o700 });
+    }
+    catch (e) {
+        if (e.code === "EEXIST")
+            throw new Error("Research directory is locked by another run. If it crashed, remove only .research-lock after confirming the process stopped.");
+        throw e;
+    }
+    try {
+        return await runCompanyResearchLocked(input);
+    }
+    finally {
+        await rmdir(lock);
+    }
+}
+async function runCompanyResearchLocked(input) {
+    const { brief, outDir, scope } = input;
+    await mkdir(outDir, { recursive: true, mode: 0o700 });
+    const fingerprint = createHash("sha256").update(JSON.stringify({ brief, scope })).digest("hex");
+    const checkpoint = path.join(outDir, "checkpoint.json");
+    let state = { fingerprint, results: {} };
+    try {
+        state = JSON.parse(await readFile(checkpoint, "utf8"));
+        if (state.fingerprint !== fingerprint)
+            throw new Error("Brief or workspace changed. Use a new output directory.");
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    const save = async (file, value) => { await writeFile(file + ".tmp", value, { mode: 0o600 }); await chmod(file + ".tmp", 0o600); await rename(file + ".tmp", file); };
+    const publish = async () => { const report = shortlistCompanyLeads(brief, state.results); await save(path.join(outDir, "contacts.csv"), companyLeadCsv(report.selected)); await save(path.join(outDir, "coverage.json"), JSON.stringify(report, null, 2)); return report; };
+    let performed = 0;
+    try {
+        for (const job of planCompanySearches(brief)) {
+            if (state.results[job.key])
+                continue;
+            if (performed >= input.maxSearches)
+                break;
+            state.results[job.key] = await input.search(job);
+            performed++;
+            await save(checkpoint, JSON.stringify(state));
+        }
+    }
+    catch (e) {
+        await publish();
+        throw e;
+    }
+    const report = await publish();
+    return { status: "ok", ...report, completedSearches: Object.keys(state.results).length, totalSearches: planCompanySearches(brief).length, output: outDir, resumable: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "salesprompter-cli",
-  "version": "0.1.73",
+  "version": "0.1.74",
   "description": "Sales workflow CLI for guided lead generation, enrichment, scoring, and sync.",
   "author": "Daniel Sinewe <hello@danielsinewe.com>",
   "type": "module",