fullstackgtm 0.50.1 → 0.51.0

package/src/cli/enrich.ts

@@ -9,6 +9,8 @@ import { createFilePlanStore } from "../planStore.ts";
 import { buildAcquirePlan, buildEnrichPlan, createFileEnrichRunStore, DEFAULT_STALE_DAYS, ENRICH_CONFIG_FILE_NAME, builtinAcquirePreset, builtinEnrichPreset, enrichRunId, inferIngestObjectType, latestStamps, loadEnrichConfig, parseCsv, resolveCrmField, selectStaleWork, stagedSourceRecords, staleDaysFor, type EnrichConfig, type EnrichCounts, type EnrichObjectType, type EnrichRun, type EnrichRunStore, type EnrichSourceRecord } from "../enrich.ts";
 import { loadMeter, remaining, type AcquireRemaining } from "../acquireMeter.ts";
 import { crmContactKeys, fetchExploriumProspects, fetchPipe0CrustdataProspectPage, partitionFreshProspects, pipe0ResolveCompanyDomains, pipe0ResolveWorkEmails, prospectIdentityKeys, type Prospect } from "../connectors/prospectSources.ts";
+import { createClaySearch, runClayPeopleSearchPage } from "../connectors/clay.ts";
+import { runContactWaterfall, type ContactProviderAdapter, type ContactWaterfallStep } from "../contactProviders.ts";
 import { loadSeen, recordSeen } from "../acquireSeen.ts";
 import { acquireCheckpointId, createFileAcquireCheckpointStore, type AcquireCheckpointKey } from "../acquireCheckpoint.ts";
 import { readHostedAcquireCheckpoint, writeHostedAcquireCheckpoint } from "../hostedAcquireCheckpoint.ts";
@@ -16,7 +18,7 @@ import { uploadHostedPatchPlan } from "../hostedPatchPlan.ts";
 import { progressReporter, reportCounts, reportEvent } from "../runReport.ts";
 import { ACQUIRE_STAGES, composeListeners, createProgressEmitter } from "../progress.ts";
 import { createLinkedInProvider, discoverLinkedInProspects } from "../acquireLinkedIn.ts";
-import { fitThreshold, icpToCrustdataFilters, icpToExploriumFilters, scoreProspectAgainstIcp, type Icp } from "../icp.ts";
+import { fitThreshold, icpToClayPeopleFilters, icpToCrustdataFilters, icpToExploriumFilters, scoreProspectAgainstIcp, type Icp } from "../icp.ts";
 import { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords, type ApolloPullKey } from "../enrichApollo.ts";
 import type { CanonicalGtmSnapshot } from "../types.ts";
 import { isSpoolPath, readSpoolPath } from "../spoolFiles.ts";
@@ -217,8 +219,8 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
     // additional per-run ceiling, never a way to exceed the budget.
     if (apiSkippedCrm || apiSkippedSeen) {
       console.error(
-        `Pre-email dedup: skipped ${apiSkippedCrm} already-in-CRM + ${apiSkippedSeen} seen before paying for emails ` +
-          `(≈$${((apiSkippedCrm + apiSkippedSeen) * costPerRecord).toFixed(2)} enrichment saved).`,
+        `Pre-enrichment dedup: skipped ${apiSkippedCrm} already-in-CRM + ${apiSkippedSeen} previously seen ` +
+          `(≈$${((apiSkippedCrm + apiSkippedSeen) * costPerRecord).toFixed(2)} downstream spend avoided).`,
       );
     }
     // `cap` is the desired create count bounded by the persistent meter. Raw
@@ -301,20 +303,16 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
     const meterLine = formatAcquireMeter(headroom, costPerRecord);
     const gaugeLine = acquireGaugeLine(headroom, config.acquire.budget ?? {}, paint(colorEnabled(process.stdout)));
     if (!save) {
-      if (rest.includes("--json")) {
-        console.log(
-          JSON.stringify(
-            { plan: result.plan, counts: result.counts, estCostUsd: result.estCostUsd, meter: headroom },
-            null,
-            2,
-          ),
-        );
-      } else {
-        console.log(verbosePlanRequested(rest) ? patchPlanToMarkdown(result.plan) : compactPlan(result.plan));
-        console.log(meterLine);
-        if (gaugeLine) console.log(gaugeLine);
-        console.log("\nDry run — nothing written. Re-run with --save to persist the plan, then approve + apply.");
-      }
+      printAcquireOutput({
+        args: rest,
+        result,
+        meter: headroom,
+        meterLine,
+        gaugeLine,
+        saved: false,
+        planSaved: false,
+        hostedPlanUrl: null,
+      });
       return;
     }
 
@@ -363,24 +361,16 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         acquireCheckpointSync.hostedVersion,
       );
     }
-    if (planIds.length > 0) {
-      const hostedRuns = hostedRunsUrl();
-      console.log(`\nSaved plan ${result.plan.id}`);
-      console.log(`  Leads      ${result.counts.created} net-new`);
-      console.log(`  Est. cost  $${result.estCostUsd.toFixed(2)}`);
-      console.log(`  Budget     ${gaugeLine ?? meterLine}`);
-      if (hostedPlanUrl) console.log(`  Plan       ${hostedPlanUrl}`);
-      if (hostedRuns) console.log(`  Observe    ${hostedRuns}`);
-      console.log("\nNext steps");
-      console.log(`  Review     fullstackgtm plans show ${result.plan.id}`);
-      console.log(`  Approve    fullstackgtm plans approve ${result.plan.id} --operations all`);
-      console.log(`  Apply      fullstackgtm apply --plan-id ${result.plan.id} --provider hubspot`);
-      console.log("\nThe meter is charged only when a create lands at apply.");
-    } else {
-      console.log(meterLine);
-      if (gaugeLine) console.log(gaugeLine);
-      console.log("No net-new leads to create (everything sourced already matched, or was withheld by the meter).");
-    }
+    printAcquireOutput({
+      args: rest,
+      result,
+      meter: headroom,
+      meterLine,
+      gaugeLine,
+      saved: true,
+      planSaved: planIds.length > 0,
+      hostedPlanUrl,
+    });
     return;
   }
 
@@ -561,8 +551,9 @@ function formatEnrichCounts(counts: EnrichCounts, ambiguities: number) {
 /**
  * Pull net-new prospects from an API acquire source into source records the
  * acquire builder dedupes + turns into create_record ops. Explorium discovers;
- * pipe0 (when resolveEmailsWith=pipe0) fills real work emails. Only rows that
- * carry the dedupe key (email) survive — you cannot resolve-first without it.
+ * A field-level provider waterfall fills missing contact data. Existing
+ * email-keyed and resolveEmailsWith=pipe0 configs translate to an implicit
+ * Pipe0 work-email step. Only rows that carry the configured dedupe key survive.
  */
 async function acquireFromApi(
   config: EnrichConfig,
@@ -602,7 +593,9 @@ async function acquireFromApi(
     ? (icp ? icpToExploriumFilters(icp) : (disc.filters ?? {}))
     : disc.provider === "pipe0"
       ? (icp ? icpToCrustdataFilters(icp) : (disc.filters ?? {}))
-      : {};
+      : disc.provider === "clay"
+        ? (icp ? icpToClayPeopleFilters(icp) : (disc.filters ?? {}))
+        : {};
   const queryFingerprint = createHash("sha256")
     .update(JSON.stringify({ source, provider: disc.provider, listId, filters, icp: icp ?? null }))
     .digest("hex");
@@ -677,6 +670,19 @@ async function acquireFromApi(
       page = result.prospects;
       cursor = result.nextCursor;
       exhausted = result.nextCursor === null;
+    } else if (disc.provider === "clay") {
+      if (!cursor) {
+        progress.note("creating Clay people-search iterator");
+        cursor = await createClaySearch({
+          apiKey: providerKey("clay"), sourceType: "people", filters,
+        });
+      }
+      const result = await runClayPeopleSearchPage({
+        apiKey: providerKey("clay"), searchId: cursor, limit: requestSize,
+      });
+      page = result.prospects;
+      offset += page.length;
+      exhausted = !result.hasMore;
     } else if (disc.provider === "explorium") {
       const pageNumber = offset + 1;
       exploriumPage = pageNumber;
@@ -695,7 +701,7 @@ async function acquireFromApi(
       offset += page.length;
       exhausted = page.length < requestSize;
     } else {
-      throw new Error(`enrich acquire: unknown discovery provider "${disc.provider}" (explorium | pipe0 | linkedin).`);
+      throw new Error(`enrich acquire: unknown discovery provider "${disc.provider}" (clay | explorium | pipe0 | linkedin).`);
     }
     discovered += page.length;
     progress.items(discovered, scanLimit);
@@ -747,23 +753,37 @@ async function acquireFromApi(
   progress.stage(ACQUIRE_STAGES[1], 1, ACQUIRE_STAGES.length);
   progress.note("checking work-email requirements");
 
-  // 3. Resolve real work emails. Triggered either when email IS the dedupe key
-  //    (Explorium's email is hashed, Crustdata returns none) or when a source
-  //    that keys on something else opts in via `resolveEmailsWith: "pipe0"`
-  //    (e.g. LinkedIn keys on the profile URL but still wants outreach emails).
-  //    pipe0 waterfall, chunked; resolves from name + company domain/name.
-  if (matchKey === "email" || disc.resolveEmailsWith === "pipe0") {
-    // The waterfall needs a company DOMAIN; LinkedIn/HeyReach lists carry only
-    // names. Resolve domains first (pipe0 company:identity) so resolution can
-    // actually land — without it, name-only resolution fails for every lead.
-    if (prospects.some((p) => !p.companyDomain && p.companyName)) {
-      progress.note(`resolving company domains for ${prospects.length} candidate(s)`);
-      const resolved = await pipe0ResolveCompanyDomains({ apiKey: providerKey("pipe0"), prospects });
-      prospects.splice(0, prospects.length, ...resolved);
+  // 3. Resolve contact fields through the ordered, fill-only waterfall. Keep
+  // legacy behavior: email-keyed acquisition and resolveEmailsWith=pipe0 imply
+  // a Pipe0 work-email step when no explicit waterfall is configured.
+  const implicitPipe0 = matchKey === "email" || disc.resolveEmailsWith === "pipe0";
+  const contactWaterfall: ContactWaterfallStep[] = disc.contactWaterfall ?? (
+    implicitPipe0 ? [{ provider: "pipe0", fields: ["work_email"] }] : []
+  );
+  if (contactWaterfall.length > 0) {
+    const adapters: Record<string, ContactProviderAdapter> = {
+      pipe0: {
+        provider: "pipe0",
+        resolve: async (candidates, fields) => {
+          let resolved = candidates;
+          if (fields.includes("work_email") && resolved.some((p) => !p.companyDomain && p.companyName)) {
+            progress.note(`resolving company domains for ${resolved.length} candidate(s)`);
+            resolved = await pipe0ResolveCompanyDomains({ apiKey: providerKey("pipe0"), prospects: resolved });
+          }
+          if (fields.includes("work_email")) {
+            progress.note(`resolving work emails with pipe0 for ${resolved.length} candidate(s)`);
+            resolved = await pipe0ResolveWorkEmails({ apiKey: providerKey("pipe0"), prospects: resolved });
+          }
+          return resolved;
+        },
+      },
+    };
+    const result = await runContactWaterfall({ prospects, steps: contactWaterfall, adapters });
+    prospects.splice(0, prospects.length, ...result.prospects);
+    for (const attempt of result.attempts) {
+      const added = Object.entries(attempt.added).map(([field, count]) => `${count} ${field}`).join(", ") || "0 fields";
+      progress.note(`${attempt.provider}: ${attempt.attempted} attempted · ${added} added`);
     }
-    progress.note(`resolving work emails for ${prospects.length} candidate(s)`);
-    const resolved = await pipe0ResolveWorkEmails({ apiKey: providerKey("pipe0"), prospects });
-    prospects.splice(0, prospects.length, ...resolved);
   }
   progress.items(prospects.length, prospects.length);
   progress.note(`${prospects.length} candidate(s) ready for planning`);
@@ -876,6 +896,61 @@ function formatAcquireMeter(headroom: AcquireRemaining, costPerRecord: number):
   );
 }
 
+function printAcquireOutput(options: {
+  args: readonly string[];
+  result: ReturnType<typeof buildAcquirePlan>;
+  meter: AcquireRemaining;
+  meterLine: string;
+  gaugeLine: string | null;
+  /** The acquisition run/checkpoint was persisted. */
+  saved: boolean;
+  /** A non-empty plan was persisted to the plan store. */
+  planSaved: boolean;
+  hostedPlanUrl: string | null;
+}): void {
+  const { args, result, meter, meterLine, gaugeLine, saved, planSaved, hostedPlanUrl } = options;
+  if (args.includes("--json")) {
+    console.log(JSON.stringify({
+      plan: result.plan,
+      counts: result.counts,
+      estCostUsd: result.estCostUsd,
+      meter,
+      persistence: {
+        runSaved: saved,
+        planSaved,
+        planId: planSaved ? result.plan.id : null,
+        hostedPlanUrl,
+      },
+    }, null, 2));
+    return;
+  }
+
+  if (verbosePlanRequested(args)) {
+    console.log(patchPlanToMarkdown(result.plan));
+    console.log(`\nAcquisition`);
+    console.log(`  Leads      ${result.counts.created} net-new · ${result.counts.unassigned} unassigned`);
+    console.log(`  Est. cost  $${result.estCostUsd.toFixed(2)}`);
+    console.log(`  Budget     ${gaugeLine ?? meterLine}`);
+    if (hostedPlanUrl) console.log(`  Plan       ${hostedPlanUrl}`);
+  } else if (planSaved || !saved) {
+    console.log(compactPlan(result.plan, { saved: planSaved }));
+    console.log(meterLine);
+    if (gaugeLine) console.log(gaugeLine);
+  } else {
+    console.log(meterLine);
+    if (gaugeLine) console.log(gaugeLine);
+    console.log("No net-new leads to create (everything sourced already matched, or was withheld by the meter).");
+  }
+
+  if (planSaved) {
+    console.log(`\nApprove  fullstackgtm plans approve ${result.plan.id} --operations all`);
+    console.log(`Apply    fullstackgtm apply --plan-id ${result.plan.id} --provider <hubspot|salesforce>`);
+    const hostedRuns = hostedRunsUrl();
+    if (hostedRuns) console.log(`Observe  ${hostedRuns}`);
+    console.log("The meter is charged only when a create lands at apply.");
+  }
+}
+
 function hostedRunsUrl(): string | null {
   const baseUrl = getCredential("broker")?.baseUrl?.replace(/\/+$/, "");
   return baseUrl ? `${baseUrl}/dashboard/runs` : null;

package/src/cli/help.ts

@@ -20,13 +20,16 @@ Usage:
   fullstackgtm login salesforce --instance-url <url> [--no-validate]  advanced: paste access token
   fullstackgtm login stripe [--no-validate]
   fullstackgtm login anthropic | openai        store an LLM API key for call parse/score
-  fullstackgtm login apollo                    store an Apollo API key for enrich pulls\n  fullstackgtm login pipe0 | explorium | theirstack  store a discovery-provider key (theirstack = technographic TAM)\n  fullstackgtm login heyreach                  store a HeyReach key for enrich acquire --source linkedin\n  fullstackgtm logout <hubspot|salesforce|stripe|anthropic|openai|apollo|pipe0|explorium|heyreach|broker>
+  fullstackgtm login apollo | clay             store a data-provider Public API key
+  fullstackgtm login pipe0 | explorium | theirstack  store a discovery-provider key (theirstack = technographic TAM)
+  fullstackgtm login heyreach                  store a HeyReach key for enrich acquire --source linkedin
+  fullstackgtm logout <hubspot|salesforce|stripe|anthropic|openai|apollo|clay|pipe0|explorium|heyreach|broker>
 
   Secrets (tokens, client secrets) are NEVER passed as flags — they leak via
   the process list and shell history. Pipe them on stdin or enter them at the
   interactive prompt:
     echo "$HUBSPOT_TOKEN" | fullstackgtm login hubspot --private-token
-  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]
                                                cold start: scaffold icp.json + enrich.config.json + a
                                                PLAYBOOK wired for this workspace (the CLI ships primitives,
                                                your agent is the orchestrator — see docs/recipes.md)
@@ -76,7 +79,7 @@ Usage:
   fullstackgtm tam estimate [--name <n>] [--icp <path>] (--accounts <n> | --source theirstack|explorium) (--acv <annual-usd> | --acv-from-crm --deal-period monthly|quarterly|annual) [--acv-basis account|buyer] [--buyers-per-account <n>] [--cross-checks <file.json>] [source options] [--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>]
                                                size the reachable market FROM the ICP (a real account count ×
                                                ACV; buyers/account = the contact population target), then fill
                                                it: populate schedules plan-only enrich acquire --save (apply
@@ -298,7 +301,7 @@ export const HELP: Record<string, HelpEntry> = {
     summary: "scaffold a workspace (icp.json + enrich.config.json + PLAYBOOK)",
     phase: "Setup",
     synopsis: [
-      "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]",
     ],
     detail:
       "Cold start: writes a starter ICP, an acquire-ready enrich.config.json (with a visible assign seam so leads are never ownerless), and a PLAYBOOK wired with the cold-start + outbound-loop recipes for this workspace. Pure file-writer — no network, keeps existing files unless --force. The CLI ships governed primitives; your coding agent is the orchestrator (see docs/recipes.md).",
@@ -312,7 +315,7 @@ export const HELP: Record<string, HelpEntry> = {
       "fullstackgtm login hubspot | salesforce          hosted browser OAuth (default)",
       "fullstackgtm login --via <hosted url>            pair with a team deployment",
       "fullstackgtm login stripe",
-      "fullstackgtm login anthropic | openai | apollo",
+      "fullstackgtm login anthropic | openai | apollo | clay",
     ],
     detail:
       "HubSpot/Salesforce use hosted browser OAuth by default; BYO app/token paths are advanced. Secrets are NEVER passed as flags — pipe on stdin or enter at the prompt: `echo \"$TOKEN\" | fullstackgtm login hubspot --private-token`.",
@@ -321,7 +324,7 @@ export const HELP: Record<string, HelpEntry> = {
   logout: {
     summary: "remove stored credentials for a provider",
     phase: "Setup",
-    synopsis: ["fullstackgtm logout <hubspot|salesforce|stripe|anthropic|openai|apollo|pipe0|explorium|broker>"],
+    synopsis: ["fullstackgtm logout <hubspot|salesforce|stripe|anthropic|openai|apollo|clay|pipe0|explorium|broker>"],
     seeAlso: ["login", "doctor"],
   },
   doctor: {

package/src/cli/init.ts

@@ -16,7 +16,7 @@ import { option } from "./shared.ts";
 export function initCommand(args: string[]) {
   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\`)
@@ -28,8 +28,8 @@ docs/recipes.md for the full play set. Existing files are kept unless --force.`)
     return;
   }
   const source = (option(args, "--source") ?? "pipe0") as InitSource;
-  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") as InitProvider;
   if (!["hubspot", "salesforce"].includes(provider)) {

package/src/cli/tam.ts

@@ -6,6 +6,7 @@ import { getCredential } from "../credentials.ts";
 import { appendCoverage, computeCoverage, coverageCountsFromSnapshot, classifyCoverage, coverageToText, deriveAcvFromClosedWon, deriveBuyersPerAccount, estimateTam, loadTamModel, projectEta, readCoverageTimeline, saveTamModel, tamReportToMarkdown, type AcvBasis, type TamCrossCheck } from "../tam.ts";
 import { probeExploriumBusinessCount } from "../connectors/prospectSources.ts";
 import { theirStackCountCompanies, theirStackPullCost, theirStackSearchCompanies } from "../connectors/theirstack.ts";
+import { clayApiKey } from "../connectors/clay.ts";
 import { icpToExploriumBusinessFilters, icpToTheirStackFilters } from "../icp.ts";
 import { scheduleCommand } from "./schedule.ts";
 import { loadIcp, numericOption, option, readSnapshot, saveRequested } from "./shared.ts";
@@ -14,7 +15,8 @@ import { unknownSubcommandError } from "./suggest.ts";
 
 /** 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: "explorium" | "pipe0" | "heyreach" | "theirstack"): string {
+export function providerKey(provider: "explorium" | "pipe0" | "clay" | "heyreach" | "theirstack"): string {
+  if (provider === "clay") return clayApiKey();
   const envName =
     provider === "explorium"
       ? "EXPLORIUM_API_KEY"
@@ -44,7 +46,7 @@ export async function tamCommand(args: string[]) {
   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/src/connectors/clay.ts

@@ -0,0 +1,155 @@
+import { getCredential } from "../credentials.ts";
+import { ProviderHttpError } from "../providerError.ts";
+import type { Prospect } from "./prospectSources.ts";
+
+export 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;
+};
+
+function clayHeaders(apiKey: string): Record<string, string> {
+  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: {
+  apiKey: string;
+  sourceType: ClaySearchSourceType;
+  filters: Record<string, unknown>;
+  fetchImpl?: typeof fetch;
+  apiBaseUrl?: string;
+}): Promise<string> {
+  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() as { search_id?: unknown; searchId?: unknown };
+  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: {
+  apiKey: string;
+  searchId: string;
+  limit?: number;
+  fetchImpl?: typeof fetch;
+  apiBaseUrl?: string;
+}): Promise<ClayPeopleSearchPage> {
+  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() as { data?: unknown; has_more?: unknown; hasMore?: unknown };
+  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: unknown): Prospect {
+  const row = value && typeof value === "object" ? value as Record<string, unknown> : {};
+  const location = row.structured_location && typeof row.structured_location === "object"
+    ? row.structured_location as Record<string, unknown>
+    : {};
+  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: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function bareDomain(value: string | undefined): string | undefined {
+  return value?.replace(/^https?:\/\//i, "").replace(/^www\./i, "").replace(/\/.*$/, "").toLowerCase() || undefined;
+}
+
+function normalizeLinkedin(value: string | undefined): string | undefined {
+  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: string,
+  fetchImpl: typeof fetch = fetch,
+  apiBaseUrl = CLAY_PUBLIC_API_BASE,
+): Promise<ClayKeyValidation> {
+  let response: 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: unknown;
+  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 as Record<string, unknown> : {};
+  const workspace = record.workspace && typeof record.workspace === "object"
+    ? record.workspace as Record<string, unknown>
+    : 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: Record<string, string | undefined> = process.env): string {
+  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/src/connectors/prospectSources.ts

@@ -34,6 +34,12 @@ 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 */
@@ -471,7 +477,7 @@ function fieldValue(field: Pipe0Field | undefined): string | 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: string | undefined): string {