salesprompter-cli 0.1.1 → 0.1.2

package/README.md

@@ -2,53 +2,206 @@
 
 `salesprompter-cli` is a JSON-first command line interface for running a practical sales workflow:
 
+- Authenticate via Salesprompter app backend
 - Define an ideal customer profile
+- Resolve a target account from a domain
 - Generate seed leads
 - Enrich leads
 - Score leads
 - Sync leads into CRM and outreach systems
+- Analyze upstream lead-list and domain-enrichment bottlenecks
+- Replace opaque Pipedream logic with deterministic CLI workflows
 
-The first version is intentionally local-first. It uses deterministic heuristics and dry-run sync providers so the command surface and data contracts are stable before real APIs are attached.
+## Integration Contract
 
-When you pass `--company-domain`, the CLI generates modeled contacts for that target account. These are synthetic leads for workflow testing, not verified real contacts.
+This CLI is not a standalone toy. It is a production integration surface for the Salesprompter app.
+
+- The Domain Finder flow in this repository is a real end-to-end test case for Salesprompter app integration.
+- CLI behavior should be treated as an app contract: auth, BigQuery execution, artifacts, and writeback semantics must remain stable.
+- Changes to domain selection, writeback, or audit logic should always be validated with:
+  - CLI tests (`npm test`)
+  - BigQuery-backed runs (`domainfinder:run:bq`, `domainfinder:audit-existing:bq`)
+  - before/after delta checks (`domainfinder:audit-delta`)
+
+The current version is account-first. It resolves a company from a domain, then generates contacts for that account through provider interfaces. The default providers are still fallback heuristics, but the JSON contracts are now stable for real company and people-data integrations.
+
+When the output `mode` is `fallback`, the leads are modeled contacts for workflow testing, not verified real contacts. A real provider path should return `mode: "real"` using the same JSON shape.
+
+All non-auth commands require a logged-in CLI session. This gives you one identity model across Salesprompter app, CLI, and Chrome extension.
+
+Global output flags:
+
+- `--json`: compact machine-readable JSON (optimized for agent/LLM parsers)
+- `--quiet`: suppress successful stdout payloads (errors still surface)
+
+## Auth and Session
+
+The CLI stores a local session file at `~/.config/salesprompter/auth-session.json` (or `SALESPROMPTER_CONFIG_DIR`).
+
+```bash
+# Device flow through Salesprompter backend (recommended)
+salesprompter auth:login
+
+# Direct login using app-issued bearer token
+salesprompter auth:login --token "$SALESPROMPTER_TOKEN"
+
+# Verify active identity with backend
+salesprompter auth:whoami --verify
+
+# Clear local session
+salesprompter auth:logout
+```
+
+Environment variables:
+
+- `SALESPROMPTER_API_BASE_URL`: override backend URL (default `https://app.salesprompter.com`)
+- `SALESPROMPTER_CONFIG_DIR`: override local config dir
+- `SALESPROMPTER_SKIP_AUTH=1`: bypass auth guard (tests/dev only)
+- `INSTANTLY_API_KEY`: required for real `sync:outreach --target instantly`
+- `INSTANTLY_CAMPAIGN_ID`: default campaign id for Instantly sync
+- `SALESPROMPTER_INSTANTLY_BASE_URL`: override Instantly API base URL (tests/local proxies)
+
+App compatibility:
+
+- If your app exposes `/api/cli/auth/device/start` and `/api/cli/auth/device/poll`, use `salesprompter auth:login`.
+- If device auth is not enabled, create a CLI token from the app endpoint `POST /api/cli/auth/token` and use:
+
+```bash
+salesprompter auth:login --token "<token-from-app>"
+```
 
 ## Why this shape works for humans and LLMs
 
 - Every command reads and writes plain JSON.
-- Output is machine-readable and composable.
+- Output is machine-readable and composable (`--json` for compact transport).
 - Domain contracts are explicit and validated with `zod`.
 - External integrations are behind narrow provider interfaces.
+- Lead generation reports which provider and mode produced the result.
+- Workflow bottlenecks become inspectable artifacts instead of hidden Pipedream state.
+- Real prospect lookup can be normalized straight into the CLI lead schema with `--lead-out`.
 
 ## Commands
 
 ```bash
 salesprompter icp:define --name "EU SaaS RevOps" \
+  --description "RevOps and sales leaders in European growth-stage software companies" \
   --industries "Software,Financial Services" \
   --company-sizes "50-199,200-499" \
   --regions "Europe" \
+  --countries "DE,NL,GB" \
   --titles "Head of Revenue Operations,VP Sales" \
   --required-signals "recent funding,growing outbound team" \
+  --keywords "revenue operations,outbound,sales tooling" \
   --out ./data/icp.json
 
+salesprompter auth:login
+salesprompter auth:whoami --verify
+salesprompter icp:vendor --vendor deel --market dach --out ./data/deel-icp.json
+salesprompter leads:lookup:bq --icp ./data/deel-icp.json --limit 100 --execute --out ./data/deel-leads-raw.json --lead-out ./data/deel-leads.json
+salesprompter leads:enrich --in ./data/deel-leads.json --out ./data/deel-enriched.json
+salesprompter leads:score --icp ./data/deel-icp.json --in ./data/deel-enriched.json --out ./data/deel-scored.json
+salesprompter sync:outreach --target instantly --in ./data/deel-scored.json --campaign-id "$INSTANTLY_CAMPAIGN_ID"
+salesprompter sync:outreach --target instantly --in ./data/deel-scored.json --campaign-id "$INSTANTLY_CAMPAIGN_ID" --apply
+salesprompter icp:from-historical-queries:bq --vendor deel --market dach --out ./data/deel-icp-historical.json --report-out ./data/deel-historical-report.json
+salesprompter leadlists:funnel:bq --vendor deel --market dach --out ./data/deel-leadlists-funnel.json
+salesprompter domainfinder:backlog:bq --market dach --out ./data/deel-domainfinder-backlog.json
+salesprompter domainfinder:candidates:bq --market dach --limit 500 --out ./data/domain-candidates.json --sql-out ./data/domain-candidates.sql
+salesprompter domainfinder:input-sql --market dach --out ./data/domainFinder_input_v2.sql
+salesprompter domainfinder:select --in ./data/domain-candidates.json --out ./data/domain-decisions.json
+salesprompter domainfinder:audit --in ./data/domain-decisions.json --out ./data/domain-audit.json
+salesprompter domainfinder:compare-pipedream --in ./data/domain-candidates.json --out ./data/domain-comparison.json
+salesprompter domainfinder:audit-existing:bq --market dach --out ./data/domain-existing-audit.json
+salesprompter domainfinder:audit-delta --before ./data/domain-existing-audit-before.json --after ./data/domain-existing-audit-after.json --out ./data/domain-existing-audit-delta.json
+salesprompter domainfinder:repair-existing:bq --market dach --mode conservative --limit 5000 --out ./data/domain-repair.sql --trace-id salesprompter-cli-repair-dach
+salesprompter domainfinder:writeback-sql --in ./data/domain-decisions.json --out ./data/domain-writeback.sql --trace-id salesprompter-cli-dach-20260308
+salesprompter domainfinder:writeback:bq --in ./data/domain-decisions.json --out ./data/domain-writeback.sql --trace-id salesprompter-cli-dach-20260308
+salesprompter domainfinder:run:bq --market dach --limit 500 --out-dir ./data/domainfinder-run --trace-id salesprompter-cli-dach-20260308
+salesprompter account:resolve --domain deel.com --company-name Deel --out ./data/deel-account.json
 salesprompter leads:generate --icp ./data/icp.json --count 5 --out ./data/leads.json
-salesprompter leads:generate --icp ./data/icp.json --count 5 --company-domain deel.com --company-name Deel --out ./data/deel-leads.json
+salesprompter leads:generate --icp ./data/icp.json --count 5 --domain deel.com --company-name Deel --out ./data/deel-leads.json
 salesprompter leads:enrich --in ./data/leads.json --out ./data/enriched.json
 salesprompter leads:score --icp ./data/icp.json --in ./data/enriched.json --out ./data/scored.json
+salesprompter leads:lookup:bq --icp ./data/deel-icp.json --limit 100
+salesprompter queries:analyze:bq --search-kind sales-people --include-function "Human Resources" --out ./data/hr-query-report.json
 salesprompter sync:crm --target hubspot --in ./data/scored.json
 salesprompter sync:outreach --target instantly --in ./data/scored.json
 ```
 
+## Domain Finder Migration
+
+The original Pipedream `domainFinder` workflow was doing three things:
+
+1. fetch a small input set from BigQuery
+2. ask OpenAI / Hunter for candidate domains
+3. pick a domain and write it back
+
+The CLI now models that logic directly and improves it:
+
+- `domainfinder:backlog:bq` measures whether the backlog is being starved before enrichment
+- `domainfinder:candidates:bq` fetches real candidate rows from BigQuery for backlog companies
+- `domainfinder:input-sql` generates a replacement input view driven by `linkedin_companies`, not `leadPool_new`
+- `domainfinder:select` applies deterministic domain selection rules
+- `domainfinder:audit` turns decisions into a review queue and writeback summary
+- `domainfinder:compare-pipedream` quantifies how often the old selector would disagree with the improved selector
+- `domainfinder:audit-existing:bq` measures current warehouse-visible mismatches and bad chosen domains
+- `domainfinder:audit-delta` compares two audit snapshots and reports metric deltas
+- `domainfinder:repair-existing:bq` generates (and optionally executes) targeted repair writes with selectable mode:
+  - `conservative`: only missing/blacklisted chosen domains
+  - `aggressive`: missing/blacklisted plus all mismatches
+  - `mismatch-only`: only mismatched chosen domains
+- `domainfinder:writeback-sql` emits conservative SQL for `domainFinder_output`
+- `domainfinder:writeback:bq` can execute that writeback in BigQuery when explicitly asked
+- `domainfinder:run:bq` runs the full candidate -> decision -> audit -> writeback pipeline and stores all artifacts
+
+Improved selection policy:
+
+1. prefer `domain_linkedin` when present and not blacklisted
+2. otherwise prefer `website_linkedin` root domain when present and not blacklisted
+3. otherwise choose the non-blacklisted candidate with the highest Hunter email count
+4. otherwise fall back to the first non-null candidate
+
+This removes the earlier failure mode where OpenAI or Hunter could override a good LinkedIn domain purely because of a higher Hunter count.
+
+Writeback policy:
+
+- write to `SalesPrompter.domainFinder_output`, which is the source feeding `linkedin_companies.domain`
+- exclude `no-domain` decisions
+- exclude blacklisted domains from generated writeback SQL
+- preserve batch provenance through `trace_id`
+
 ## Development
 
 ```bash
 npm install
 npm run build
 node ./dist/cli.js --help
+npm test
 ```
 
+BigQuery project selection:
+
+- The CLI runs `bq query` with `--project_id` from `BQ_PROJECT_ID`.
+- Fallback order: `BQ_PROJECT_ID` -> `GOOGLE_CLOUD_PROJECT` -> `GCLOUD_PROJECT` -> `icpidentifier`.
+
+## Real Deel Flow
+
+For Deel as the vendor you sell for, do not use `--domain deel.com`. That path targets contacts at Deel itself.
+
+Use this path instead:
+
+1. `salesprompter icp:vendor --vendor deel --market dach --out ./data/deel-icp.json`
+2. `salesprompter leads:lookup:bq --icp ./data/deel-icp.json --limit 100 --execute --out ./data/deel-leads-raw.json --lead-out ./data/deel-leads.json`
+3. `salesprompter leads:enrich --in ./data/deel-leads.json --out ./data/deel-enriched.json`
+4. `salesprompter leads:score --icp ./data/deel-icp.json --in ./data/deel-enriched.json --out ./data/deel-scored.json`
+5. `salesprompter sync:outreach --target instantly --in ./data/deel-scored.json --campaign-id "$INSTANTLY_CAMPAIGN_ID"`
+6. Add `--apply` only when the dry-run output looks correct.
+
 ## Next integrations
 
-- Replace `HeuristicLeadProvider` with Apollo, Clay, LinkedIn, or custom data providers.
+- Replace `HeuristicCompanyProvider` with a real account lookup provider.
+- Replace `HeuristicPeopleSearchProvider` with Apollo, Clay, LinkedIn, or custom people-data providers.
 - Replace `HeuristicEnrichmentProvider` with enrichment APIs such as Clearbit, FullEnrich, or custom LLM workflows.
 - Replace `DryRunSyncProvider` with real HubSpot, Salesforce, Pipedrive, Instantly, Apollo, or Outreach clients.
-- Add prompt-oriented commands so an LLM can ask for ICP refinement or lead prioritization directly through the CLI.
+- Add provider selection and credentials for a first real `--domain deel.com` workflow.
+- Replace configurable `bq` field mapping with a typed adapter per warehouse schema.
+- Add a real candidate-fetch command that reads domain candidates from BigQuery and feeds them into `domainfinder:select`.

package/dist/auth.js

@@ -0,0 +1,242 @@
+import os from "node:os";
+import path from "node:path";
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { z } from "zod";
+const DEFAULT_API_BASE_URL = "https://app.salesprompter.com";
+const CLIENT_HEADER = "salesprompter-cli/0.2";
+const DEFAULT_DEVICE_POLL_INTERVAL_SECONDS = 3;
+const DEFAULT_DEVICE_TIMEOUT_SECONDS = 180;
+const UserSchema = z.object({
+    id: z.string().min(1),
+    email: z.string().email(),
+    name: z.string().min(1).optional()
+});
+const AuthSessionSchema = z.object({
+    accessToken: z.string().min(1),
+    refreshToken: z.string().min(1).optional(),
+    apiBaseUrl: z.string().url(),
+    user: UserSchema,
+    expiresAt: z.string().datetime().optional(),
+    createdAt: z.string().datetime()
+});
+const DeviceStartResponseSchema = z.object({
+    deviceCode: z.string().min(1),
+    userCode: z.string().min(1),
+    verificationUrl: z.string().url().optional(),
+    verificationUri: z.string().url().optional(),
+    intervalSeconds: z.number().int().min(1).optional(),
+    expiresInSeconds: z.number().int().min(30).optional()
+});
+const DevicePollPendingSchema = z.object({
+    status: z.literal("pending")
+});
+const DevicePollDeniedSchema = z.object({
+    status: z.enum(["denied", "expired"])
+});
+const DevicePollAuthorizedSchema = z.object({
+    status: z.literal("authorized"),
+    accessToken: z.string().min(1),
+    refreshToken: z.string().min(1).optional(),
+    expiresAt: z.string().datetime().optional(),
+    user: UserSchema
+});
+const DevicePollResponseSchema = z.union([
+    DevicePollPendingSchema,
+    DevicePollDeniedSchema,
+    DevicePollAuthorizedSchema
+]);
+const WhoAmIResponseSchema = z
+    .union([
+    z.object({
+        user: UserSchema,
+        expiresAt: z.string().datetime().optional()
+    }),
+    z.object({
+        id: z.string().min(1),
+        email: z.string().email(),
+        name: z.string().min(1).optional(),
+        expiresAt: z.string().datetime().optional()
+    }),
+    z.object({
+        data: z.object({
+            user: UserSchema,
+            expiresAt: z.string().datetime().optional()
+        })
+    })
+])
+    .transform((value) => {
+    if ("data" in value) {
+        return value.data;
+    }
+    if ("user" in value) {
+        return value;
+    }
+    return {
+        user: {
+            id: value.id,
+            email: value.email,
+            name: value.name
+        },
+        expiresAt: value.expiresAt
+    };
+});
+function getConfigDir() {
+    const override = process.env.SALESPROMPTER_CONFIG_DIR?.trim();
+    if (override !== undefined && override.length > 0) {
+        return override;
+    }
+    return path.join(os.homedir(), ".config", "salesprompter");
+}
+function getSessionPath() {
+    return path.join(getConfigDir(), "auth-session.json");
+}
+function normalizeApiBaseUrl(apiBaseUrl) {
+    const value = (apiBaseUrl ?? process.env.SALESPROMPTER_API_BASE_URL ?? DEFAULT_API_BASE_URL).trim();
+    return value.replace(/\/+$/, "");
+}
+async function hasSessionFile() {
+    try {
+        await access(getSessionPath());
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function httpJson(url, init, schema) {
+    const response = await fetch(url, init);
+    const text = await response.text();
+    const payload = text.length > 0 ? JSON.parse(text) : {};
+    if (!response.ok) {
+        throw new Error(`request failed (${response.status}) for ${url}`);
+    }
+    return schema.parse(payload);
+}
+function hasExpired(expiresAt) {
+    if (expiresAt === undefined) {
+        return false;
+    }
+    return Date.now() >= Date.parse(expiresAt);
+}
+export async function readAuthSession() {
+    if (!(await hasSessionFile())) {
+        return null;
+    }
+    const content = await readFile(getSessionPath(), "utf8");
+    const parsed = JSON.parse(content);
+    return AuthSessionSchema.parse(parsed);
+}
+export async function writeAuthSession(session) {
+    const sessionPath = getSessionPath();
+    await mkdir(path.dirname(sessionPath), { recursive: true });
+    await writeFile(sessionPath, `${JSON.stringify(session, null, 2)}\n`, "utf8");
+}
+export async function clearAuthSession() {
+    await rm(getSessionPath(), { force: true });
+}
+export async function requireAuthSession() {
+    const session = await readAuthSession();
+    if (session === null) {
+        throw new Error("not logged in. Run `salesprompter auth:login`.");
+    }
+    if (hasExpired(session.expiresAt)) {
+        throw new Error("session expired. Run `salesprompter auth:login`.");
+    }
+    return session;
+}
+export async function verifySession(session) {
+    const apiBaseUrl = normalizeApiBaseUrl(session.apiBaseUrl);
+    const response = await httpJson(`${apiBaseUrl}/api/cli/auth/me`, {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${session.accessToken}`,
+            "X-Salesprompter-Client": CLIENT_HEADER
+        }
+    }, WhoAmIResponseSchema);
+    return AuthSessionSchema.parse({
+        ...session,
+        apiBaseUrl,
+        user: response.user,
+        expiresAt: response.expiresAt ?? session.expiresAt
+    });
+}
+export async function loginWithToken(token, apiBaseUrl) {
+    const normalizedApiBaseUrl = normalizeApiBaseUrl(apiBaseUrl);
+    const response = await httpJson(`${normalizedApiBaseUrl}/api/cli/auth/me`, {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "X-Salesprompter-Client": CLIENT_HEADER
+        }
+    }, WhoAmIResponseSchema);
+    const session = AuthSessionSchema.parse({
+        accessToken: token,
+        apiBaseUrl: normalizedApiBaseUrl,
+        user: response.user,
+        expiresAt: response.expiresAt,
+        createdAt: new Date().toISOString()
+    });
+    await writeAuthSession(session);
+    return session;
+}
+export async function loginWithDeviceFlow(options) {
+    const apiBaseUrl = normalizeApiBaseUrl(options?.apiBaseUrl);
+    const timeoutSeconds = options?.timeoutSeconds ?? DEFAULT_DEVICE_TIMEOUT_SECONDS;
+    let start;
+    try {
+        start = await httpJson(`${apiBaseUrl}/api/cli/auth/device/start`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Salesprompter-Client": CLIENT_HEADER
+            },
+            body: JSON.stringify({ client: "salesprompter-cli" })
+        }, DeviceStartResponseSchema);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("(404)")) {
+            throw new Error("device login is not configured on this Salesprompter app. Generate a CLI token in the app and run `salesprompter auth:login --token <token>`.");
+        }
+        throw error;
+    }
+    const verificationUrl = start.verificationUrl ?? start.verificationUri;
+    if (verificationUrl === undefined) {
+        throw new Error("device start response missing verification url");
+    }
+    const pollIntervalMs = (start.intervalSeconds ?? DEFAULT_DEVICE_POLL_INTERVAL_SECONDS) * 1000;
+    const deadline = Date.now() + Math.max(timeoutSeconds, 30) * 1000;
+    while (Date.now() < deadline) {
+        const poll = await httpJson(`${apiBaseUrl}/api/cli/auth/device/poll`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Salesprompter-Client": CLIENT_HEADER
+            },
+            body: JSON.stringify({ deviceCode: start.deviceCode })
+        }, DevicePollResponseSchema);
+        if (poll.status === "authorized") {
+            const session = AuthSessionSchema.parse({
+                accessToken: poll.accessToken,
+                refreshToken: poll.refreshToken,
+                apiBaseUrl,
+                user: poll.user,
+                expiresAt: poll.expiresAt,
+                createdAt: new Date().toISOString()
+            });
+            await writeAuthSession(session);
+            return { session, verificationUrl, userCode: start.userCode };
+        }
+        if (poll.status === "denied") {
+            throw new Error("login denied");
+        }
+        if (poll.status === "expired") {
+            throw new Error("device login expired");
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    throw new Error("timed out waiting for device login");
+}
+export function shouldBypassAuth() {
+    return process.env.SALESPROMPTER_SKIP_AUTH === "1";
+}

package/dist/bigquery.js

@@ -0,0 +1,194 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const DEFAULT_BQ_PROJECT_ID = process.env.BQ_PROJECT_ID ?? process.env.GOOGLE_CLOUD_PROJECT ?? process.env.GCLOUD_PROJECT ?? "icpidentifier";
+function escapeSqlString(value) {
+    return value.replaceAll("\\", "\\\\").replaceAll("'", "\\'");
+}
+function lowerQuoted(value) {
+    return `'${escapeSqlString(value.trim().toLowerCase())}'`;
+}
+function upperQuoted(value) {
+    return `'${escapeSqlString(value.trim().toUpperCase())}'`;
+}
+function buildContainsClause(field, values) {
+    const normalized = values.map((value) => value.trim()).filter((value) => value.length > 0);
+    if (normalized.length === 0) {
+        return null;
+    }
+    const clauses = normalized.map((value) => `LOWER(CAST(${field} AS STRING)) LIKE ${lowerQuoted(`%${value}%`)}`);
+    return `(${clauses.join(" OR ")})`;
+}
+function buildInClause(field, values) {
+    const normalized = values.map((value) => value.trim().toLowerCase()).filter((value) => value.length > 0);
+    if (normalized.length === 0) {
+        return null;
+    }
+    return `LOWER(CAST(${field} AS STRING)) IN (${normalized.map(lowerQuoted).join(", ")})`;
+}
+function buildCountryClause(field, values) {
+    const normalized = values.map((value) => value.trim().toUpperCase()).filter((value) => value.length > 0);
+    if (normalized.length === 0) {
+        return null;
+    }
+    return `UPPER(CAST(${field} AS STRING)) IN (${normalized.map(upperQuoted).join(", ")})`;
+}
+function buildCompanySizeClause(field, buckets) {
+    const normalized = buckets.map((value) => value.trim()).filter((value) => value.length > 0);
+    if (normalized.length === 0) {
+        return null;
+    }
+    const bucketMap = {
+        "1-49": ["1-10", "11-50"],
+        "50-199": ["51-200"],
+        "200-499": ["201-500"],
+        "500+": ["501-1000", "1001-5000", "5001-10.000", "10.000+"]
+    };
+    const expanded = normalized.flatMap((bucket) => bucketMap[bucket] ?? [bucket]);
+    const clauses = expanded.map((bucket) => `LOWER(CAST(${field} AS STRING)) = ${lowerQuoted(bucket)}`);
+    return `(${clauses.join(" OR ")})`;
+}
+function requireString(row, field) {
+    const value = String(row[field] ?? "").trim();
+    if (value.length === 0) {
+        throw new Error(`BigQuery lead row missing required field: ${field}`);
+    }
+    return value;
+}
+function employeeCountFromBucket(bucket) {
+    switch (bucket.trim()) {
+        case "1-10":
+            return 10;
+        case "11-50":
+            return 30;
+        case "51-200":
+            return 125;
+        case "201-500":
+            return 350;
+        case "501-1000":
+            return 750;
+        case "1001-5000":
+            return 2500;
+        case "5001-10.000":
+            return 7500;
+        case "10.000+":
+            return 10000;
+        default:
+            return 250;
+    }
+}
+function deriveRegion(country, region) {
+    const normalizedRegion = region.trim();
+    if (normalizedRegion.length > 0) {
+        return normalizedRegion;
+    }
+    const normalizedCountry = country.trim().toUpperCase();
+    if (["DE", "AT", "CH"].includes(normalizedCountry)) {
+        return "DACH";
+    }
+    return normalizedCountry.length > 0 ? normalizedCountry : "unknown";
+}
+export function normalizeBigQueryLeadRows(rows) {
+    return rows.map((row) => {
+        const firstName = String(row.firstName ?? "").trim();
+        const lastName = String(row.lastName ?? "").trim();
+        const contactName = [firstName, lastName].filter((value) => value.length > 0).join(" ");
+        if (contactName.length === 0) {
+            throw new Error("BigQuery lead row missing required name fields");
+        }
+        const companySize = requireString(row, "companySize");
+        const country = String(row.country ?? "").trim();
+        const region = String(row.region ?? "").trim();
+        return {
+            companyName: requireString(row, "companyName"),
+            domain: requireString(row, "domain"),
+            industry: requireString(row, "industry"),
+            region: deriveRegion(country, region),
+            employeeCount: employeeCountFromBucket(companySize),
+            contactName,
+            title: requireString(row, "title"),
+            email: requireString(row, "email"),
+            source: "bigquery-leadpool",
+            signals: []
+        };
+    });
+}
+export function buildBigQueryLeadLookupSql(icp, options) {
+    const filters = [
+        buildContainsClause(options.titleField, icp.titles),
+        buildInClause(options.industryField, icp.industries),
+        options.regionField ? buildInClause(options.regionField, icp.regions) : null,
+        buildCountryClause(options.countryField, icp.countries),
+        buildCompanySizeClause(options.companySizeField, icp.companySizes)
+    ].filter((value) => value !== null);
+    if (options.useSalesprompterGuards) {
+        filters.push(`${options.emailField} IS NOT NULL`, `COALESCE(email_invalid, FALSE) = FALSE`, `COALESCE(company_blacklisted, FALSE) = FALSE`, `COALESCE(company_inSequence, FALSE) = FALSE`, `COALESCE(contact_replied, FALSE) = FALSE`, `COALESCE(contact_bounced, FALSE) = FALSE`, `COALESCE(jobTitle_blacklisted, FALSE) = FALSE`);
+    }
+    const keywordSearchExpression = options.keywordFields.length > 0
+        ? `CONCAT(${options.keywordFields.map((field) => `COALESCE(CAST(${field} AS STRING), '')`).join(", ' ', ")})`
+        : null;
+    const keywordClause = keywordSearchExpression ? buildContainsClause(keywordSearchExpression, icp.keywords) : null;
+    if (keywordClause !== null) {
+        filters.push(keywordClause);
+    }
+    const excludedKeywordClause = keywordSearchExpression ? buildContainsClause(keywordSearchExpression, icp.excludedKeywords) : null;
+    if (excludedKeywordClause !== null) {
+        filters.push(`NOT ${excludedKeywordClause}`);
+    }
+    if (options.additionalWhere !== undefined && options.additionalWhere.trim().length > 0) {
+        filters.push(`(${options.additionalWhere.trim()})`);
+    }
+    const whereClause = filters.length > 0 ? filters.join("\n  AND ") : "TRUE";
+    return [
+        "SELECT",
+        `  ${options.companyField} AS companyName,`,
+        `  ${options.domainField} AS domain,`,
+        `  ${options.titleField} AS title,`,
+        `  ${options.firstNameField} AS firstName,`,
+        `  ${options.lastNameField} AS lastName,`,
+        `  ${options.emailField} AS email,`,
+        `  ${options.industryField} AS industry,`,
+        `  ${options.companySizeField} AS companySize,`,
+        `  ${options.countryField} AS country,`,
+        options.regionField ? `  ${options.regionField} AS region` : "  CAST(NULL AS STRING) AS region",
+        `FROM \`${options.table}\``,
+        "WHERE",
+        `  ${whereClause}`,
+        `LIMIT ${options.limit}`
+    ].join("\n");
+}
+export async function runBigQueryQuery(sql, options = {}) {
+    const args = [
+        "query",
+        "--use_legacy_sql=false",
+        "--format=prettyjson",
+        `--project_id=${DEFAULT_BQ_PROJECT_ID}`
+    ];
+    if (options.maxRows !== undefined) {
+        args.push(`--max_rows=${options.maxRows}`);
+    }
+    args.push(sql);
+    const { stdout } = await execFileAsync("bq", args);
+    return JSON.parse(stdout);
+}
+export async function executeBigQuerySql(sql, options = {}) {
+    const args = [
+        "query",
+        "--use_legacy_sql=false",
+        "--format=prettyjson",
+        `--project_id=${DEFAULT_BQ_PROJECT_ID}`
+    ];
+    if (options.maxRows !== undefined) {
+        args.push(`--max_rows=${options.maxRows}`);
+    }
+    args.push(sql);
+    const { stdout } = await execFileAsync("bq", args);
+    return stdout.trim();
+}
+export async function runBigQueryRows(sql, options = {}) {
+    const result = await runBigQueryQuery(sql, options);
+    if (!Array.isArray(result)) {
+        throw new Error("expected BigQuery query result to be an array");
+    }
+    return result;
+}