fullstackgtm 0.50.1 → 0.52.0

package/dist/cli/icp.js

@@ -1,13 +1,18 @@
 // Extracted verbatim from src/cli.ts (mechanical split, no behavior change).
 import { readFileSync, writeFileSync } from "node:fs";
+import { emitKeypressEvents } from "node:readline";
+import { createInterface } from "node:readline/promises";
 import { resolve } from "node:path";
 import { resolveLlmCredential } from "../llm.js";
 import { fitThreshold, icpFromAnswers, icpToCrustdataFilters, icpToExploriumFilters, INTERVIEW_SPEC } from "../icp.js";
 import { createFileSignalStore, DEFAULT_SIGNALS_CONFIG } from "../signals.js";
 import { createFileJudgeStore, DEFAULT_JUDGE_PROMPT, judgeRunId, judgeSignals } from "../judge.js";
 import { DEFAULT_GOLDEN_NOW_ISO, DEFAULT_GOLDEN_SET, DEFAULT_MIN_ACCURACY, defaultJudgeFn, gradeAgainstOutcomes, gradeJudge, parseGoldenSet } from "../judgeEval.js";
-import { loadIcp, numericOption, option, readSnapshot, resolveLlmBaseUrls, saveRequested } from "./shared.js";
+import { loadIcp, numericOption, option, readSecret, readSnapshot, resolveLlmBaseUrls, saveRequested } from "./shared.js";
 import { createStatusLine } from "./ui.js";
+import { box, colorEnabled, paint } from "./ui.js";
+import { getCredential, storeCredential } from "../credentials.js";
+import { deriveWebsiteIcp, icpReviewSegments, OPENROUTER_API_BASE } from "../icpDerive.js";
 import { unknownSubcommandError } from "./suggest.js";
 function renderJudgeDecisions(decisions) {
     if (decisions.length === 0)
@@ -23,6 +28,120 @@ function renderJudgeDecisions(decisions) {
     }
     return lines.join("\n");
 }
+function updateReviewSegment(icp, id, raw) {
+    const values = raw.split(",").map((value) => value.trim()).filter(Boolean);
+    if (id === "threshold")
+        return { ...icp, scoring: { ...icp.scoring, threshold: Number(raw) } };
+    if (["industries", "employeeBands", "geos", "technologies"].includes(id)) {
+        return { ...icp, firmographics: { ...icp.firmographics, [id]: values } };
+    }
+    if (["titleKeywords", "jobLevels", "departments"].includes(id)) {
+        return { ...icp, persona: { ...icp.persona, [id]: values } };
+    }
+    return { ...icp, signals: { ...icp.signals, intentTopics: values } };
+}
+function renderDerivedIcp(result, selected = -1) {
+    const p = paint(colorEnabled());
+    const segments = icpReviewSegments(result.icp);
+    const lines = [
+        `${result.company.name}  ${result.company.domain}`,
+        `${Math.round(result.confidence * 100)}% confidence · ${result.derivation.model}`,
+        "",
+        ...segments.map((segment, index) => `${index === selected ? "›" : " "} ${segment.label.padEnd(15)} ${segment.value}`),
+        "",
+        selected >= 0 ? "↑/↓ select · enter edit · s save · q cancel" : `${result.evidence.length} website-verifiable evidence quote(s)`,
+    ];
+    return box(lines, p, "ICP preview").join("\n");
+}
+async function resolveIcpDeriveLlm(args) {
+    const requested = option(args, "--provider")?.toLowerCase();
+    if (requested && !["openrouter", "openai", "anthropic"].includes(requested)) {
+        throw new Error(`icp derive --provider must be openrouter, openai, or anthropic; got "${requested}".`);
+    }
+    const openRouterKey = process.env.OPENROUTER_API_KEY ?? getCredential("openrouter")?.accessToken;
+    const normal = resolveLlmCredential();
+    if ((!requested || requested === "openrouter") && openRouterKey) {
+        return { provider: "openai", apiKey: openRouterKey, openaiBaseUrl: OPENROUTER_API_BASE };
+    }
+    if (requested === "openai" || requested === "anthropic") {
+        const envKey = requested === "openai" ? process.env.OPENAI_API_KEY : process.env.ANTHROPIC_API_KEY;
+        const key = envKey ?? getCredential(requested)?.accessToken;
+        if (key)
+            return { provider: requested, apiKey: key, ...resolveLlmBaseUrls() };
+    }
+    if (normal && (!requested || requested === normal.provider))
+        return { ...normal, ...resolveLlmBaseUrls() };
+    const provider = requested;
+    if (!process.stdin.isTTY || process.env.CI) {
+        throw new Error("ICP derivation needs an LLM key. Run one of:\n" +
+            "  fullstackgtm login openrouter\n  fullstackgtm login openai\n  fullstackgtm login anthropic\n" +
+            "Then rerun the same icp derive command.");
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    const answer = provider ?? ((await rl.question("LLM provider [openrouter/openai/anthropic] (openrouter): ")).trim().toLowerCase() || "openrouter");
+    rl.close();
+    if (!['openrouter', 'openai', 'anthropic'].includes(answer))
+        throw new Error(`Unknown LLM provider "${answer}".`);
+    const selectedProvider = answer;
+    const key = await readSecret(`${selectedProvider} API key`);
+    if (!key)
+        throw new Error(`No ${answer} API key provided.`);
+    const now = new Date().toISOString();
+    storeCredential(selectedProvider, { kind: "api_key", accessToken: key, createdAt: now, updatedAt: now });
+    console.error(`Stored ${selectedProvider} key in the active FullStackGTM profile.`);
+    return selectedProvider === "openrouter"
+        ? { provider: "openai", apiKey: key, openaiBaseUrl: OPENROUTER_API_BASE }
+        : { provider: selectedProvider, apiKey: key };
+}
+async function reviewDerivedIcp(result) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return result;
+    let current = result;
+    let selected = 0;
+    const render = () => process.stdout.write(`\u001b[2J\u001b[H${renderDerivedIcp(current, selected)}\n`);
+    emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode?.(true);
+    process.stdin.resume();
+    render();
+    return new Promise((resolveReview) => {
+        const finish = (value) => {
+            process.stdin.off("keypress", onKey);
+            process.stdin.setRawMode?.(false);
+            process.stdin.pause();
+            resolveReview(value);
+        };
+        const onKey = async (_input, key) => {
+            const segments = icpReviewSegments(current.icp);
+            if (key.ctrl && key.name === "c" || key.name === "q")
+                return finish(null);
+            if (key.name === "up") {
+                selected = (selected - 1 + segments.length) % segments.length;
+                return render();
+            }
+            if (key.name === "down") {
+                selected = (selected + 1) % segments.length;
+                return render();
+            }
+            if (key.name === "s")
+                return finish(current);
+            if (key.name !== "return")
+                return;
+            process.stdin.off("keypress", onKey);
+            process.stdin.setRawMode?.(false);
+            const segment = segments[selected];
+            const rl = createInterface({ input: process.stdin, output: process.stderr });
+            const answer = await rl.question(`\n${segment.label} [${segment.value}]: `);
+            rl.close();
+            if (answer.trim())
+                current = { ...current, icp: updateReviewSegment(current.icp, segment.id, answer) };
+            emitKeypressEvents(process.stdin);
+            process.stdin.setRawMode?.(true);
+            process.stdin.on("keypress", onKey);
+            render();
+        };
+        process.stdin.on("keypress", onKey);
+    });
+}
 /**
  * `icp` — develop and inspect the Ideal Customer Profile that targets acquire.
  * The CLI can't run AskUserQuestion itself; `icp interview` emits the question
@@ -36,6 +155,8 @@ export async function icpCommand(args) {
     if (!sub || args.includes("--help") || args.includes("-h")) {
         console.log(`Usage:
   fullstackgtm icp interview                      emit the interview spec (an agent drives it with AskUserQuestion)
+  fullstackgtm icp derive --domain <site> [--model <id>] [--out icp.json] [--json]
+                                                derive an evidence-backed ICP from a public website (OpenRouter/OpenAI/Anthropic)
   fullstackgtm icp set <answers.json> [--name <n>] [--out <path>]   write icp.json from interview answers
   fullstackgtm icp show [--icp <path>]            render the ICP + the discovery filters it produces
   fullstackgtm icp judge [--signals-from latest|<label>] [--with-history] [--prompt <path>] [--min-score 0] [--save]   rank unjudged signals into send/nurture/skip decisions (timing x fit x memory)
@@ -56,6 +177,39 @@ ops. Develop one by interview, then \`enrich acquire\` picks up ./icp.json.
         }, null, 2));
         return;
     }
+    if (sub === "derive") {
+        const domain = option(rest, "--domain");
+        if (!domain)
+            throw new Error("Usage: fullstackgtm icp derive --domain <company.com> [--out icp.json] [--json]");
+        const llm = await resolveIcpDeriveLlm(rest);
+        const status = createStatusLine();
+        let derived;
+        try {
+            derived = await deriveWebsiteIcp({
+                domain,
+                llm,
+                model: option(rest, "--model") ?? undefined,
+                onProgress: (event) => status.set(event.message),
+            });
+        }
+        finally {
+            status.done();
+        }
+        if (!rest.includes("--json") && !rest.includes("--no-interactive")) {
+            const reviewed = await reviewDerivedIcp(derived);
+            if (!reviewed)
+                throw new Error("ICP review cancelled; no file was written.");
+            derived = reviewed;
+        }
+        const out = option(rest, "--out");
+        if (out) {
+            const path = resolve(process.cwd(), out);
+            writeFileSync(path, `${JSON.stringify(derived.icp, null, 2)}\n`);
+            console.error(`Wrote reviewed ICP to ${path}. Next: fullstackgtm enrich acquire --source clay --icp ${path}`);
+        }
+        console.log(rest.includes("--json") ? JSON.stringify(derived, null, 2) : renderDerivedIcp(derived));
+        return;
+    }
     if (sub === "set") {
         const file = rest.find((a) => !a.startsWith("--"));
         if (!file)

package/dist/cli/init.js

@@ -13,7 +13,7 @@ import { option } from "./shared.js";
 export function initCommand(args) {
     if (args.includes("--help") || args.includes("-h")) {
         console.log(`Usage:
-  fullstackgtm init [--source pipe0|explorium|linkedin] [--provider hubspot|salesforce] [--out <dir>] [--force]
+  fullstackgtm init [--source pipe0|explorium|clay|linkedin] [--provider hubspot|salesforce] [--out <dir>] [--force]
 
 Scaffolds a workspace so the first acquire/signals/judge/draft commands work:
   icp.json            starter ICP (edit, or rebuild with \`icp interview\`)
@@ -25,8 +25,8 @@ docs/recipes.md for the full play set. Existing files are kept unless --force.`)
         return;
     }
     const source = (option(args, "--source") ?? "pipe0");
-    if (!["pipe0", "explorium", "linkedin"].includes(source)) {
-        throw new Error(`init: --source must be pipe0|explorium|linkedin (got "${source}")`);
+    if (!["pipe0", "explorium", "clay", "linkedin"].includes(source)) {
+        throw new Error(`init: --source must be pipe0|explorium|clay|linkedin (got "${source}")`);
     }
     const provider = (option(args, "--provider") ?? "hubspot");
     if (!["hubspot", "salesforce"].includes(provider)) {

package/dist/cli/tam.d.ts

@@ -1,6 +1,6 @@
 /** Best-effort enrich-config load for apply-time acquire-budget enforcement. */
 /** Provider API key: env override first, then the credential store (`login`). */
-export declare function providerKey(provider: "explorium" | "pipe0" | "heyreach" | "theirstack"): string;
+export declare function providerKey(provider: "explorium" | "pipe0" | "clay" | "heyreach" | "theirstack"): string;
 /**
  * `tam` — Total Addressable Market mapping. Estimate a defensible universe from
  * the ICP, then iteratively populate it via scheduled governed acquire runs and

package/dist/cli/tam.js

@@ -5,6 +5,7 @@ import { getCredential } from "../credentials.js";
 import { appendCoverage, computeCoverage, coverageCountsFromSnapshot, classifyCoverage, coverageToText, deriveAcvFromClosedWon, deriveBuyersPerAccount, estimateTam, loadTamModel, projectEta, readCoverageTimeline, saveTamModel, tamReportToMarkdown } from "../tam.js";
 import { probeExploriumBusinessCount } from "../connectors/prospectSources.js";
 import { theirStackCountCompanies, theirStackPullCost, theirStackSearchCompanies } from "../connectors/theirstack.js";
+import { clayApiKey } from "../connectors/clay.js";
 import { icpToExploriumBusinessFilters, icpToTheirStackFilters } from "../icp.js";
 import { scheduleCommand } from "./schedule.js";
 import { loadIcp, numericOption, option, readSnapshot, saveRequested } from "./shared.js";
@@ -12,6 +13,8 @@ import { unknownSubcommandError } from "./suggest.js";
 /** Best-effort enrich-config load for apply-time acquire-budget enforcement. */
 /** Provider API key: env override first, then the credential store (`login`). */
 export function providerKey(provider) {
+    if (provider === "clay")
+        return clayApiKey();
     const envName = provider === "explorium"
         ? "EXPLORIUM_API_KEY"
         : provider === "pipe0"
@@ -41,7 +44,7 @@ export async function tamCommand(args) {
   fullstackgtm tam accounts [--name <n>] [--icp <path>] --source theirstack [--max <n>] [--dry-run | --confirm] [--max-credits <n>] [--usd-per-credit <r>] [--out <file.csv> | --json]
   fullstackgtm tam status   [--name <n>] <source options> [--save] [--json]
   fullstackgtm tam report   [--name <n>] [--out <path>]
-  fullstackgtm tam populate [--name <n>] --cron "<expr>" [--source pipe0|explorium|linkedin] [--provider hubspot|salesforce] [--label <l>]
+  fullstackgtm tam populate [--name <n>] --cron "<expr>" [--source pipe0|explorium|clay|linkedin] [--provider hubspot|salesforce] [--label <l>]
 
 Estimate the reachable market FROM your ICP: a real account count × a confirmed
 ANNUAL ACV (--acv <annual-usd>, or --acv-from-crm --deal-period monthly|quarterly|

package/dist/connectors/clay.d.ts

@@ -0,0 +1,33 @@
+import type { Prospect } from "./prospectSources.ts";
+export declare const CLAY_PUBLIC_API_BASE = "https://api.clay.com/public/v0";
+export type ClayKeyValidation = {
+    ok: boolean;
+    detail: string;
+    workspaceId?: string;
+};
+export type ClaySearchSourceType = "people" | "companies";
+export type ClayPeopleSearchPage = {
+    prospects: Prospect[];
+    hasMore: boolean;
+};
+/** Create a forward-only Clay search iterator. This call does not fetch a page. */
+export declare function createClaySearch(opts: {
+    apiKey: string;
+    sourceType: ClaySearchSourceType;
+    filters: Record<string, unknown>;
+    fetchImpl?: typeof fetch;
+    apiBaseUrl?: string;
+}): Promise<string>;
+/** Consume the next people page from a Clay search iterator. */
+export declare function runClayPeopleSearchPage(opts: {
+    apiKey: string;
+    searchId: string;
+    limit?: number;
+    fetchImpl?: typeof fetch;
+    apiBaseUrl?: string;
+}): Promise<ClayPeopleSearchPage>;
+export declare function normalizeClayPerson(value: unknown): Prospect;
+/** Validate a Clay Public API key without creating a search or spending enrichment credits. */
+export declare function validateClayApiKey(apiKey: string, fetchImpl?: typeof fetch, apiBaseUrl?: string): Promise<ClayKeyValidation>;
+/** Resolve Clay credentials using the standard env -> profile-scoped store ladder. */
+export declare function clayApiKey(env?: Record<string, string | undefined>): string;

package/dist/connectors/clay.js

@@ -0,0 +1,123 @@
+import { getCredential } from "../credentials.js";
+import { ProviderHttpError } from "../providerError.js";
+export const CLAY_PUBLIC_API_BASE = "https://api.clay.com/public/v0";
+function clayHeaders(apiKey) {
+    return { "clay-api-key": apiKey, Accept: "application/json", "Content-Type": "application/json" };
+}
+/** Create a forward-only Clay search iterator. This call does not fetch a page. */
+export async function createClaySearch(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const base = (opts.apiBaseUrl ?? CLAY_PUBLIC_API_BASE).replace(/\/$/, "");
+    const response = await fetchImpl(`${base}/search/filters-mode`, {
+        method: "POST",
+        headers: clayHeaders(opts.apiKey),
+        body: JSON.stringify({ source_type: opts.sourceType, filters: opts.filters }),
+    });
+    if (!response.ok)
+        throw new ProviderHttpError("Clay", "create search", response.status);
+    const body = await response.json();
+    const searchId = body.search_id ?? body.searchId;
+    if (typeof searchId !== "string" || !searchId)
+        throw new Error("Clay create search returned no search_id.");
+    return searchId;
+}
+/** Consume the next people page from a Clay search iterator. */
+export async function runClayPeopleSearchPage(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const base = (opts.apiBaseUrl ?? CLAY_PUBLIC_API_BASE).replace(/\/$/, "");
+    const limit = Math.max(1, Math.min(opts.limit ?? 25, 100));
+    const response = await fetchImpl(`${base}/search/filters-mode/${encodeURIComponent(opts.searchId)}/run`, {
+        method: "POST",
+        headers: clayHeaders(opts.apiKey),
+        body: JSON.stringify({ limit }),
+    });
+    if (!response.ok)
+        throw new ProviderHttpError("Clay", "run people search", response.status);
+    const body = await response.json();
+    if (!Array.isArray(body.data))
+        throw new Error("Clay people search returned an invalid data array.");
+    const hasMore = body.has_more ?? body.hasMore;
+    if (typeof hasMore !== "boolean")
+        throw new Error("Clay people search returned no has_more flag.");
+    return { prospects: body.data.map(normalizeClayPerson), hasMore };
+}
+export function normalizeClayPerson(value) {
+    const row = value && typeof value === "object" ? value : {};
+    const location = row.structured_location && typeof row.structured_location === "object"
+        ? row.structured_location
+        : {};
+    const fullName = stringValue(row.name);
+    return {
+        firstName: stringValue(row.first_name),
+        lastName: stringValue(row.last_name),
+        fullName,
+        jobTitle: stringValue(row.latest_experience_title),
+        companyName: stringValue(row.latest_experience_company),
+        companyDomain: bareDomain(stringValue(row.domain)),
+        linkedin: normalizeLinkedin(stringValue(row.url)),
+        headline: undefined,
+        sourceId: normalizeLinkedin(stringValue(row.url)) ?? fullName,
+        location: {
+            city: stringValue(location.city),
+            state: stringValue(location.state),
+            region: stringValue(location.region),
+            country: stringValue(location.country),
+            countryCode: stringValue(location.country_iso),
+        },
+    };
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function bareDomain(value) {
+    return value?.replace(/^https?:\/\//i, "").replace(/^www\./i, "").replace(/\/.*$/, "").toLowerCase() || undefined;
+}
+function normalizeLinkedin(value) {
+    if (!value)
+        return undefined;
+    const normalized = value.startsWith("http") ? value : `https://${value.replace(/^\/+/, "")}`;
+    return normalized.replace(/\/$/, "");
+}
+/** Validate a Clay Public API key without creating a search or spending enrichment credits. */
+export async function validateClayApiKey(apiKey, fetchImpl = fetch, apiBaseUrl = CLAY_PUBLIC_API_BASE) {
+    let response;
+    try {
+        response = await fetchImpl(`${apiBaseUrl.replace(/\/$/, "")}/me`, {
+            headers: { "clay-api-key": apiKey, Accept: "application/json" },
+        });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return { ok: false, detail: `Cannot reach the Clay Public API: ${detail}` };
+    }
+    if (!response.ok)
+        return { ok: false, detail: `Clay rejected the key: HTTP ${response.status}` };
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        return { ok: false, detail: "Clay accepted the request but returned an invalid JSON response." };
+    }
+    const record = body && typeof body === "object" ? body : {};
+    const workspace = record.workspace && typeof record.workspace === "object"
+        ? record.workspace
+        : undefined;
+    const rawWorkspaceId = record.workspace_id ?? record.workspaceId ?? workspace?.id;
+    const workspaceId = typeof rawWorkspaceId === "string" || typeof rawWorkspaceId === "number"
+        ? String(rawWorkspaceId)
+        : undefined;
+    return {
+        ok: true,
+        detail: workspaceId ? `Key accepted by Clay workspace ${workspaceId}.` : "Key accepted by the Clay Public API.",
+        workspaceId,
+    };
+}
+/** Resolve Clay credentials using the standard env -> profile-scoped store ladder. */
+export function clayApiKey(env = process.env) {
+    const key = env.CLAY_API_KEY ?? getCredential("clay")?.accessToken;
+    if (key)
+        return key;
+    throw new Error('No Clay credentials. Run `clay api-keys create --name "fullstackgtm"`, then pipe the key to ' +
+        '`fullstackgtm login clay`, or set CLAY_API_KEY.');
+}

package/dist/connectors/prospectSources.d.ts

@@ -32,6 +32,18 @@ export type Prospect = {
     linkedin?: string;
     /** real work email once resolved (pipe0); never the hashed value */
     email?: string;
+    /** Validated mobile number when a contact provider explicitly returns one. */
+    mobile?: string;
+    /** Validated business direct dial when distinct from mobile. */
+    directDial?: string;
+    /** Person geography returned by identity-search providers. */
+    location?: {
+        city?: string;
+        state?: string;
+        region?: string;
+        country?: string;
+        countryCode?: string;
+    };
     /** ICP fit score 0..1, set by the acquire scorer */
     fitScore?: number;
     /** provider-native id for traceability */

package/dist/connectors/prospectSources.js

@@ -313,7 +313,7 @@ function fieldValue(field) {
     return typeof v === "string" && v.trim() ? v : undefined;
 }
 // ---------------------------------------------------------------------------
-// Pre-email dedup: identity keys shared between prospects and CRM contacts, so
+// Pre-enrichment dedup: identity keys shared between prospects and CRM contacts, so
 // we can drop already-in-CRM / already-seen people BEFORE paying for emails.
 function normName(value) {
     return (value ?? "").trim().toLowerCase().replace(/\s+/g, " ");

package/dist/contactProviders.d.ts

@@ -0,0 +1,44 @@
+import type { Prospect } from "./connectors/prospectSources.ts";
+export type ContactField = "work_email" | "mobile" | "direct_dial";
+export type ContactInputShape = "linkedin" | "name_domain" | "email" | "phone" | "company_domain";
+export type ContactProviderExecution = "sync" | "poll" | "webhook" | "batch";
+export type ContactProviderBilling = "per_attempt" | "per_match" | "per_field" | "subscription" | "unknown";
+export type ContactProviderCapability = {
+    provider: string;
+    operation: string;
+    inputShapes: ContactInputShape[];
+    outputFields: ContactField[];
+    execution: ContactProviderExecution;
+    billing: ContactProviderBilling;
+    chargesOn: Array<"request" | "match" | "valid" | "accept_all" | "unknown">;
+    supportsBalance: boolean;
+    supportsIdempotency: boolean;
+    maxBatchSize?: number;
+};
+/** Only implemented adapters belong here; planned providers stay in the strategy document. */
+export declare const CONTACT_PROVIDER_CAPABILITIES: Readonly<Record<string, readonly ContactProviderCapability[]>>;
+export type ContactWaterfallStep = {
+    provider: string;
+    fields: ContactField[];
+};
+export type ContactProviderAdapter = {
+    provider: string;
+    resolve(prospects: Prospect[], fields: ContactField[]): Promise<Prospect[]>;
+};
+export type ContactWaterfallAttempt = {
+    provider: string;
+    fields: ContactField[];
+    attempted: number;
+    added: Partial<Record<ContactField, number>>;
+};
+export type ContactWaterfallResult = {
+    prospects: Prospect[];
+    attempts: ContactWaterfallAttempt[];
+};
+export declare function validateContactWaterfall(steps: ContactWaterfallStep[]): ContactWaterfallStep[];
+/** Run providers in order. Later steps receive only records still missing a requested field. */
+export declare function runContactWaterfall(opts: {
+    prospects: Prospect[];
+    steps: ContactWaterfallStep[];
+    adapters: Readonly<Record<string, ContactProviderAdapter>>;
+}): Promise<ContactWaterfallResult>;

package/dist/contactProviders.js

@@ -0,0 +1,100 @@
+/** Only implemented adapters belong here; planned providers stay in the strategy document. */
+export const CONTACT_PROVIDER_CAPABILITIES = {
+    pipe0: [{
+            provider: "pipe0",
+            operation: "person:workemail:waterfall@1",
+            inputShapes: ["name_domain"],
+            outputFields: ["work_email"],
+            execution: "batch",
+            billing: "per_attempt",
+            chargesOn: ["request"],
+            supportsBalance: false,
+            supportsIdempotency: false,
+            maxBatchSize: 100,
+        }],
+};
+export function validateContactWaterfall(steps) {
+    if (!Array.isArray(steps) || steps.length === 0) {
+        throw new Error("contact waterfall must contain at least one provider step");
+    }
+    return steps.map((step, index) => {
+        if (!step || typeof step.provider !== "string" || !step.provider.trim()) {
+            throw new Error(`contact waterfall step ${index + 1}: provider must be a non-empty string`);
+        }
+        const capabilities = CONTACT_PROVIDER_CAPABILITIES[step.provider];
+        if (!capabilities) {
+            throw new Error(`contact waterfall step ${index + 1}: unsupported provider "${step.provider}" ` +
+                `(implemented: ${Object.keys(CONTACT_PROVIDER_CAPABILITIES).join(", ")})`);
+        }
+        if (!Array.isArray(step.fields) || step.fields.length === 0) {
+            throw new Error(`contact waterfall step ${index + 1}: fields must be a non-empty array`);
+        }
+        const fields = [...new Set(step.fields)];
+        for (const field of fields) {
+            if (field !== "work_email" && field !== "mobile" && field !== "direct_dial") {
+                throw new Error(`contact waterfall step ${index + 1}: unsupported field "${String(field)}"`);
+            }
+            if (!capabilities.some((capability) => capability.outputFields.includes(field))) {
+                const available = [...new Set(capabilities.flatMap((capability) => capability.outputFields))];
+                throw new Error(`contact waterfall step ${index + 1}: ${step.provider} does not implement "${field}" ` +
+                    `(available: ${available.join(", ")})`);
+            }
+        }
+        return { provider: step.provider, fields };
+    });
+}
+/** Run providers in order. Later steps receive only records still missing a requested field. */
+export async function runContactWaterfall(opts) {
+    const steps = validateContactWaterfall(opts.steps);
+    const prospects = opts.prospects.map((prospect) => ({ ...prospect }));
+    const attempts = [];
+    for (const step of steps) {
+        const adapter = opts.adapters[step.provider];
+        if (!adapter)
+            throw new Error(`contact waterfall: adapter "${step.provider}" is not configured`);
+        const indexes = prospects
+            .map((prospect, index) => step.fields.some((field) => !fieldValue(prospect, field)) ? index : -1)
+            .filter((index) => index >= 0);
+        if (indexes.length === 0) {
+            attempts.push({ provider: step.provider, fields: step.fields, attempted: 0, added: {} });
+            continue;
+        }
+        const inputs = indexes.map((index) => prospects[index]);
+        const outputs = await adapter.resolve(inputs, step.fields);
+        if (outputs.length !== inputs.length) {
+            throw new Error(`contact waterfall: ${step.provider} returned ${outputs.length} result(s) for ${inputs.length} input(s)`);
+        }
+        const added = {};
+        outputs.forEach((output, outputIndex) => {
+            const prospectIndex = indexes[outputIndex];
+            const current = prospects[prospectIndex];
+            let merged = current;
+            for (const field of step.fields) {
+                if (fieldValue(current, field))
+                    continue;
+                const value = fieldValue(output, field);
+                if (!value)
+                    continue;
+                merged = setFieldValue(merged, field, value);
+                added[field] = (added[field] ?? 0) + 1;
+            }
+            prospects[prospectIndex] = merged;
+        });
+        attempts.push({ provider: step.provider, fields: step.fields, attempted: inputs.length, added });
+    }
+    return { prospects, attempts };
+}
+function fieldValue(prospect, field) {
+    if (field === "work_email")
+        return prospect.email;
+    if (field === "mobile")
+        return prospect.mobile;
+    return prospect.directDial;
+}
+function setFieldValue(prospect, field, value) {
+    if (field === "work_email")
+        return { ...prospect, email: value };
+    if (field === "mobile")
+        return { ...prospect, mobile: value };
+    return { ...prospect, directDial: value };
+}

package/dist/enrich.d.ts

@@ -1,6 +1,7 @@
 import type { AcquireBudget } from "./acquireMeter.ts";
 import type { ProgressEmitter } from "./progress.ts";
 import type { AssignmentContext, AssignmentPolicy } from "./assign.ts";
+import { type ContactWaterfallStep } from "./contactProviders.ts";
 import type { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
 /**
  * The enrich layer: governed append/refresh of third-party data into the CRM.
@@ -83,11 +84,16 @@ export type AcquireCreateMap = {
  * real emails (e.g. explorium discovers, pipe0 resolves the work email).
  */
 export type AcquireDiscoveryConfig = {
-    provider: "explorium" | "pipe0" | "linkedin" | "heyreach";
+    provider: "explorium" | "pipe0" | "clay" | "linkedin" | "heyreach";
+    /** Clay search collection. Phase 1 supports people; companies follows separately. */
+    sourceType?: "people" | "companies";
     filters?: Record<string, unknown>;
     size?: number;
     /** Maximum raw provider candidates scanned per run while seeking fresh leads. */
     scanLimit?: number;
+    /** Ordered fill-only contact providers. Later steps receive only unresolved fields. */
+    contactWaterfall?: ContactWaterfallStep[];
+    /** @deprecated Use contactWaterfall. Retained for existing configurations. */
     resolveEmailsWith?: "pipe0";
     /** LinkedIn sources only: the provider-native list id to read (HeyReach lead-list id). */
     listId?: string;