fullstackgtm 0.50.0 → 0.51.0

package/dist/cli/schedule.js

@@ -8,6 +8,7 @@ import { computeMissedFirings, createFileScheduleRunStore, createFileScheduleSto
 import { runCli } from "../cli.js";
 import { isOptionValue, numericOption, option } from "./shared.js";
 import { unknownSubcommandError } from "./suggest.js";
+import { colorEnabled, paint, table } from "./ui.js";
 /**
  * The schedule layer: declarative cadences for read/plan-side commands,
  * materialized through a provider (MVP: the user crontab), with an
@@ -113,10 +114,19 @@ trigger: manual. status shows next firing and surfaces missed firings
             console.log('No schedules. Add one with `fullstackgtm schedule add "<command>" --cron "<expr>"`.');
             return;
         }
-        for (const entry of withNext) {
-            console.log(`${entry.id}  ${entry.enabled ? "on " : "off"}  ${entry.cron.padEnd(14)} next ${entry.nextFiring ?? "—"}  ${entry.label}: ${entry.argv.join(" ")}`);
-        }
-        console.log("\nEntries are declarative — `schedule install` materializes enabled ones into the crontab.");
+        const p = paint(colorEnabled(process.stdout));
+        const verbose = rest.includes("--verbose");
+        const rows = [
+            ["STATE", "SCHEDULE", "NEXT", ...(verbose ? ["CRON", "COMMAND"] : [])],
+            ...withNext.map((entry) => [
+                entry.enabled ? "on" : "off",
+                `${entry.label} · ${entry.id}`,
+                entry.nextFiring ?? "—",
+                ...(verbose ? [entry.cron, entry.argv.join(" ")] : []),
+            ]),
+        ];
+        console.log(table(rows, [p.dim, null, null]).join("\n"));
+        console.log("\nDeclarative only · run `fullstackgtm schedule install` after changes.");
         return;
     }
     if (subcommand === "remove") {
@@ -251,20 +261,21 @@ trigger: manual. status shows next firing and surfaces missed firings
             const last = entry.lastRun;
             const streak = entry.streak;
             const missed = entry.missedFirings;
-            console.log(`${entry.id}  ${entry.enabled ? "on " : "off"}  ${entry.cron}  ${entry.label}: ${entry.argv.join(" ")}`);
-            console.log(`  next: ${entry.nextFiring ?? "— (disabled)"}`);
+            const verbose = rest.includes("--verbose");
+            const outcome = !last ? "never run" : last.exitCode === 0 ? (last.noopReason ? `no-op · ${last.noopReason}` : "healthy") : `failed · exit ${last.exitCode}`;
+            console.log(`${entry.enabled ? "●" : "○"} ${entry.label} · ${outcome}`);
+            console.log(`  ${entry.id} · next ${entry.nextFiring ?? "— (disabled)"}`);
+            if (verbose)
+                console.log(`  ${entry.argv.join(" ")} · cron ${entry.cron}`);
             if (last) {
                 const artifacts = [
                     ...last.artifacts.planIds.map((planId) => `plan ${planId}`),
                     ...last.artifacts.runLabels.map((runLabel) => `run ${runLabel}`),
                 ];
-                console.log(`  last: ${last.firedAt} (${last.trigger}) exit ${last.exitCode}` +
-                    (last.noopReason ? ` — no-op: ${last.noopReason}` : "") +
-                    (artifacts.length ? ` — ${artifacts.join(", ")}` : ""));
-                console.log(`  streak: ${streak.length} ${streak.outcome}(s)`);
+                console.log(`  last ${last.firedAt} · ${last.trigger} · ${streak.length} ${streak.outcome}${streak.length === 1 ? "" : "s"}${artifacts.length ? ` · ${artifacts.join(", ")}` : ""}`);
             }
             else {
-                console.log("  last: never fired");
+                console.log("  last never fired");
             }
             if (missed.length > 0) {
                 console.log(`  missed: ${missed.length}${entry.missedFiringsCapped ? "+" : ""} expected firing(s) with no run record ` +

package/dist/cli/signals.js

@@ -22,6 +22,20 @@ function resolveSignalsConfig(args) {
         return loadSignalsConfig(local);
     return DEFAULT_SIGNALS_CONFIG;
 }
+function concise(value, max = 72) {
+    const oneLine = value.replace(/\s+/g, " ").trim();
+    return oneLine.length <= max ? oneLine : `${oneLine.slice(0, max - 1)}…`;
+}
+function renderSignals(signals) {
+    if (signals.length === 0)
+        return "No signals matched.";
+    const lines = [`Fresh signals (${signals.length})`, ""];
+    for (const signal of signals) {
+        lines.push(`${signal.weight.toFixed(2).padStart(5)}  ${signal.accountDomain}  · ${signal.bucket}`);
+        lines.push(`       ${concise(signal.trigger)}`);
+    }
+    return lines.join("\n");
+}
 /**
  * Resolve the watchlist of accounts to scan. Sources, in precedence order:
  *  - a --watchlist file (JSON array of {domain, boards?} or bare domain strings),
@@ -211,7 +225,7 @@ from the credential ladder, never argv; --connector-opt carries non-secret knobs
         const { fresh, deduped } = dedupeSignals(candidates, priorSignals, config.dedupWindowDays, now);
         const ranked = [...fresh].sort((a, b) => b.weight - a.weight || a.accountDomain.localeCompare(b.accountDomain));
         // Ranked fresh signals to stdout; guidance to stderr.
-        console.log(JSON.stringify(ranked, null, 2));
+        console.log(rest.includes("--json") || rest.includes("--verbose") ? JSON.stringify(ranked, null, 2) : renderSignals(ranked));
         console.error(`Fetched ${fetched} candidate signal(s); ${fresh.length} fresh, ${deduped.length} deduped ` +
             `(window ${config.dedupWindowDays}d). NO plan emitted — signals are read-only re: CRM.`);
         const save = saveRequested(rest);
@@ -259,7 +273,7 @@ from the credential ladder, never argv; --connector-opt carries non-secret knobs
             return true;
         });
         const ranked = filtered.sort((a, b) => b.weight - a.weight || a.accountDomain.localeCompare(b.accountDomain));
-        console.log(JSON.stringify(ranked, null, 2));
+        console.log(rest.includes("--json") || rest.includes("--verbose") ? JSON.stringify(ranked, null, 2) : renderSignals(ranked));
         console.error(`${ranked.length} signal(s)${unjudgedOnly ? " (unjudged)" : ""}.`);
         return;
     }
@@ -286,7 +300,12 @@ from the credential ladder, never argv; --connector-opt carries non-secret knobs
         const outcomes = await store.listOutcomes();
         const signalsById = new Map((await store.allSignals()).map((s) => [s.id, s]));
         const weights = computeWeights(config, outcomes, signalsById);
-        console.log(JSON.stringify(weights, null, 2));
+        if (rest.includes("--json") || rest.includes("--verbose")) {
+            console.log(JSON.stringify(weights, null, 2));
+        }
+        else {
+            console.log(["Learned signal weights", "", ...SIGNAL_BUCKETS.map((bucket) => `${bucket.padEnd(10)} ${weights[bucket].toFixed(4)}`)].join("\n"));
+        }
         if (rest.includes("--explain")) {
             // Per-bucket config default vs learned + booked/total over credited signals.
             const booked = new Map();

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|
@@ -253,9 +256,18 @@ RevOps universe, with real names. --source explorium is a firmographic count onl
             writeFileSync(resolve(process.cwd(), out), md);
             console.log(`Wrote ${out}.`);
         }
-        else {
+        else if (rest.includes("--verbose")) {
             console.log(md);
         }
+        else if (timeline.length > 0) {
+            console.log(coverageToText(model, timeline.at(-1), eta));
+            console.log("\nUse --verbose for assumptions, cross-checks, and the full coverage history.");
+        }
+        else {
+            console.log(`TAM "${model.name}" · ${model.universe.accounts.toLocaleString()} accounts · ${model.universe.contacts.toLocaleString()} buyers · $${Math.round(model.tamUsd).toLocaleString()}`);
+            console.log(`ICP ${model.icpName} · ${model.acv.basis}-basis ACV $${Math.round(model.acv.valueUsd).toLocaleString()} (${model.acv.source})`);
+            console.log("No coverage readings yet. Run `fullstackgtm tam status --save` to establish one; use --verbose for the full assumptions report.");
+        }
         return;
     }
     if (sub === "populate") {

package/dist/cli/ui.js

@@ -262,8 +262,12 @@ export function createChecklist(items, stream = process.stderr, env = process.en
             const label = entry.state === "pending" ? p.dim(item.label.padEnd(labelWidth)) : item.label.padEnd(labelWidth);
             return `  ${glyph} ${label}${note}`;
         });
-        const up = painted > 0 ? `\u001b[${painted}A` : "";
-        stream.write(`${up}${lines.map((line) => `\u001b[2K${line}`).join("\n")}\n`);
+        // Keep the cursor on the board's last row while it is live. A trailing
+        // newline on every repaint can scroll the old top row into permanent
+        // history when the board sits at the bottom of the terminal, producing
+        // apparent duplicate/errored frames in terminal captures.
+        const up = painted > 1 ? `\u001b[${painted - 1}A` : "";
+        stream.write(`${up}${lines.map((line) => `\u001b[2K${line}`).join("\n")}`);
         painted = lines.length;
     };
     const start = () => {
@@ -292,14 +296,18 @@ export function createChecklist(items, stream = process.stderr, env = process.en
             timer = null;
             if (options.persist) {
                 // The caller's final state update already painted the completed board.
-                // Freeze that frame in scrollback; repainting here can leave both the
-                // last live frame and the final frame visible in some terminals.
+                // Advance exactly once so subsequent output begins below it.
+                if (painted > 0)
+                    stream.write("\n");
                 painted = 0;
                 return;
             }
             if (painted > 0) {
-                // Erase the board: cursor up over every painted line, clear each.
-                stream.write(`\u001b[${painted}A${"\u001b[2K\n".repeat(painted)}\u001b[${painted}A`);
+                // Erase in place without linefeeds, which could themselves scroll.
+                const up = painted > 1 ? `\u001b[${painted - 1}A` : "";
+                const clear = Array.from({ length: painted }, (_, index) => `\u001b[2K${index < painted - 1 ? "\u001b[1B" : ""}`).join("");
+                const restore = painted > 1 ? `\u001b[${painted - 1}A` : "";
+                stream.write(`${up}${clear}${restore}`);
                 painted = 0;
             }
         },

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/hubspot.d.ts

@@ -18,6 +18,10 @@ export type HubspotConnectorOptions = {
      * alongside the legacy `onProgress` callback; both are presentation-only.
      */
     progress?: ProgressEmitter;
+    /** Maximum retries for HubSpot 429/5xx responses (default 5). */
+    maxRetries?: number;
+    /** Injectable delay for deterministic retry tests. */
+    sleep?: (milliseconds: number) => Promise<void>;
 };
 /**
  * Reference connector for HubSpot.

package/dist/connectors/hubspot.js

@@ -30,6 +30,8 @@ const PULL_STAGE_BY_TYPE = {
 export function createHubspotConnector(options) {
     const baseUrl = (options.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
     const fetchImpl = options.fetchImpl ?? fetch;
+    const maxRetries = options.maxRetries ?? 5;
+    const sleep = options.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
     const mappings = options.fieldMappings;
     // create:<Name> dedup within one connector lifetime (one apply run): the
     // search API is eventually consistent, so a just-created company is
@@ -66,28 +68,44 @@ export function createHubspotConnector(options) {
         emitter.items(fetched);
     };
     async function request(path, init = {}) {
-        const token = await options.getAccessToken();
         let response;
-        try {
-            response = await fetchImpl(`${baseUrl}${path}`, {
-                ...init,
-                headers: {
-                    Authorization: `Bearer ${token}`,
-                    "Content-Type": "application/json",
-                    ...(init.headers ?? {}),
-                },
-            });
-        }
-        catch (error) {
-            const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
-            throw new Error(`Cannot reach HubSpot at ${baseUrl}${cause}. Check network access.`);
-        }
-        if (!response.ok) {
+        for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+            const token = await options.getAccessToken();
+            try {
+                response = await fetchImpl(`${baseUrl}${path}`, {
+                    ...init,
+                    headers: {
+                        Authorization: `Bearer ${token}`,
+                        "Content-Type": "application/json",
+                        ...(init.headers ?? {}),
+                    },
+                });
+            }
+            catch (error) {
+                const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+                throw new Error(`Cannot reach HubSpot at ${baseUrl}${cause}. Check network access.`);
+            }
+            const retryable = response.status === 429 || response.status >= 500;
+            if (!retryable || attempt === maxRetries)
+                break;
+            await response.text().catch(() => undefined);
+            const retryAfter = response.headers.get("Retry-After");
+            const seconds = retryAfter === null ? NaN : Number(retryAfter);
+            const dateDelay = retryAfter && !Number.isFinite(seconds) ? Date.parse(retryAfter) - Date.now() : NaN;
+            const delayMs = Math.min(30_000, Math.max(0, Number.isFinite(seconds) ? seconds * 1_000 : Number.isFinite(dateDelay) ? dateDelay : 1_000 * 2 ** attempt));
+            const reason = response.status === 429 ? "rate limited" : `temporarily unavailable (${response.status})`;
+            options.progress?.note(`HubSpot ${reason}; retrying in ${Math.ceil(delayMs / 1_000)}s (${attempt + 1}/${maxRetries})`);
+            await sleep(delayMs);
+        }
+        if (!response || !response.ok) {
             // Status line only — HubSpot 4xx bodies echo submitted property values
             // (contact emails, company domains) and the request payload, and these
             // errors are persisted into scheduled-run records. Never interpolate it.
-            await response.text().catch(() => undefined);
-            throw new Error(`HubSpot API error ${response.status}. Check the token scopes and request.`);
+            await response?.text().catch(() => undefined);
+            if (response?.status === 429) {
+                throw new Error(`HubSpot rate limit (429) persisted after ${maxRetries} retries. Wait for the portal limit to reset, then retry; no CRM writes were made.`);
+            }
+            throw new Error(`HubSpot API error ${response?.status ?? "unknown"}. Check the token scopes and request.`);
         }
         // DELETE and some association writes return 204 with an empty body.
         const text = await response.text();

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 };
+}