fullstackgtm 0.57.0 → 0.58.0

package/dist/cli/enrich.d.ts

@@ -1,6 +1,6 @@
 /**
- * The enrich layer: governed append/refresh of third-party data (Apollo pull,
- * Clay ingest) into the CRM through the normal dry-run → approval → apply
+ * The enrich layer: governed append/refresh of third-party data (Apollo or
+ * ZoomInfo pull, Clay ingest) into the CRM through the normal dry-run → approval → apply
  * contract. State lives in the profile-scoped run store (checkpoint,
  * staleness ledger, observability in one); scheduling belongs to the
  * horizontal scheduler — enrich owns no cron logic.

package/dist/cli/enrich.js

@@ -19,6 +19,7 @@ import { ACQUIRE_STAGES, composeListeners, createProgressEmitter } from "../prog
 import { createLinkedInProvider, discoverLinkedInProspects } from "../acquireLinkedIn.js";
 import { clayPeopleFilterRoutes, fitThreshold, icpToClayInvestmentCompanyFilters, icpToClayPeopleFilters, icpToCrustdataFilters, icpToExploriumFilters, scoreProspectAgainstIcp } from "../icp.js";
 import { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords } from "../enrichApollo.js";
+import { createZoomInfoClient, pullZoomInfoRecords } from "../enrichZoomInfo.js";
 import { isSpoolPath, readSpoolPath } from "../spoolFiles.js";
 import { isOptionValue, loadIcp, numericOption, option, readSnapshot, saveRequested } from "./shared.js";
 import { providerKey } from "./tam.js";
@@ -28,8 +29,8 @@ import { compactPlan, verbosePlanRequested } from "./planOutput.js";
 import { writeHostedArtifact } from "../hostedArtifacts.js";
 import { readIcpSyncState } from "../icpSync.js";
 /**
- * The enrich layer: governed append/refresh of third-party data (Apollo pull,
- * Clay ingest) into the CRM through the normal dry-run → approval → apply
+ * The enrich layer: governed append/refresh of third-party data (Apollo or
+ * ZoomInfo pull, Clay ingest) into the CRM through the normal dry-run → approval → apply
  * contract. State lives in the profile-scoped run store (checkpoint,
  * staleness ledger, observability in one); scheduling belongs to the
  * horizontal scheduler — enrich owns no cron logic.
@@ -71,8 +72,9 @@ and leaves them unassigned. Backfill existing ownerless records with
 \`reassign --assign-unowned --to <ownerId>\`.
 
 append pulls from an api source (Apollo — BYO key via \`login apollo\` or
-APOLLO_API_KEY) or reads data staged by \`enrich ingest\` (Clay CSV exports,
-webhook payload JSON), matches source records to CRM records via the ordered
+APOLLO_API_KEY; ZoomInfo — official \`gtm\` CLI via \`gtm auth login\`) or reads
+data staged by \`enrich ingest\` (Clay CSV exports, webhook payload JSON),
+matches source records to CRM records via the ordered
 match keys in enrich.config.json (unique hit wins; zero hits falls through to
 the next key; multiple hits skip or flow into the suggest chain, per
 onAmbiguous), and emits a fill-blanks-only patch plan. Without --save it
@@ -232,6 +234,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         // piped) and, via the composed reporter, heartbeat to a paired hosted app.
         // The meter reading (creates vs headroom + budget burn) rides the same
         // emitter, feeding the dashboard's gauge without printing anything new.
+        const acquireRunLabel = option(rest, "--run-label") ?? `acquire-${source}-${today}`;
         let result;
         try {
             acquireProgress.stage(ACQUIRE_STAGES[2], 2, ACQUIRE_STAGES.length);
@@ -244,7 +247,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
                 source,
                 snapshot,
                 records,
-                runLabel: option(rest, "--run-label") ?? `acquire-${source}-${today}`,
+                runLabel: acquireRunLabel,
                 maxRecords: cap,
                 progress: acquireProgress,
             });
@@ -259,7 +262,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         // Observability: headline metrics for the web run timeline (paired users).
         reportCounts({
             sourced: result.counts.fetched,
-            created: result.counts.created,
+            proposed: result.counts.created,
             withheldByMeter: result.counts.withheldByMeter,
             skippedInCrm: apiSkippedCrm,
             skippedSeen: apiSkippedSeen,
@@ -270,9 +273,9 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         const icpPath = resolve(process.cwd(), option(rest, "--icp") ?? "icp.json");
         const trackedIcp = existsSync(icpPath) ? readIcpSyncState(icpPath) : null;
         const leadMirror = await writeHostedArtifact({
-            kind: "lead_run", key: `leads:${result.plan.id}`, label: result.plan.title ?? result.plan.id,
+            kind: "lead_run", key: `leads:${result.plan.id}`, label: acquireRunLabel,
             domain: trackedIcp?.domain,
-            document: { runLabel: result.plan.id, createdAt: new Date().toISOString(), source, counts: result.counts,
+            document: { runLabel: acquireRunLabel, createdAt: new Date().toISOString(), source, targetDomain: option(rest, "--company-domain"), counts: result.counts,
                 plan: result.plan, icpRef: trackedIcp ? { artifactId: trackedIcp.artifactId, domain: trackedIcp.domain, revision: trackedIcp.revision, localIcpSha256: trackedIcp.localIcpSha256 } : undefined },
         });
         if (leadMirror.status === "saved")
@@ -386,10 +389,17 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
                 : "Nothing to refresh: no stale records carry a pull key (companies need a domain, contacts an email).");
             return;
         }
-        const client = createApolloClient({
-            getApiKey: () => apolloApiKey(),
-            apiBaseUrl: process.env.APOLLO_API_BASE_URL,
-        });
+        if (source !== "apollo" && source !== "zoominfo") {
+            throw new Error(`enrich ${mode}: api source "${source}" supports acquire discovery, not snapshot enrichment. ` +
+                "Use apollo or zoominfo for append/refresh, or stage records with `enrich ingest`.");
+        }
+        const apolloClient = source === "apollo"
+            ? createApolloClient({
+                getApiKey: () => apolloApiKey(),
+                apiBaseUrl: process.env.APOLLO_API_BASE_URL,
+            })
+            : null;
+        const zoomInfoClient = source === "zoominfo" ? createZoomInfoClient() : null;
         if (save) {
             run = await openEnrichRun(store, source, mode, option(rest, "--run-label"), today);
             if (run.cursor) {
@@ -403,7 +413,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         let pullProcessed = 0;
         let result;
         try {
-            result = await pullApolloRecords(client, pullKeys, {
+            const pullOptions = {
                 resumeAfter: run?.cursor ?? null,
                 onProgress: async (progress) => {
                     if (pullBar.active) {
@@ -422,7 +432,10 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
                         run.missedKeys = [...(run.missedKeys ?? []), progress.miss.value];
                     await store.update(run);
                 },
-            });
+            };
+            result = source === "zoominfo"
+                ? await pullZoomInfoRecords(zoomInfoClient, pullKeys, pullOptions)
+                : await pullApolloRecords(apolloClient, pullKeys, pullOptions);
         }
         finally {
             pullBar.done();

package/dist/cli/help.js

@@ -86,7 +86,7 @@ Usage:
   fullstackgtm enrich refresh [--source apollo] [--stale-days <n>] [--save] [--config <path>] [source options]
   fullstackgtm enrich ingest <file.csv|payload.json|spool.jsonl|spool-dir> --source clay [--run-label <label>]
   fullstackgtm enrich status [--runs] [--source <id>] [--json]
-                                               governed enrichment: pull (Apollo) or stage (Clay) third-party
+                                               governed enrichment: pull (Apollo/ZoomInfo) or stage (Clay) third-party
                                                data, match it to CRM records deterministically, and emit a
                                                fill-blanks-only patch plan through the normal dry-run →
                                                approve → apply gate. refresh re-checks stale stamped fields
@@ -481,7 +481,7 @@ export const HELP = {
         seeAlso: ["enrich", "plans", "apply", "resolve"],
     },
     enrich: {
-        summary: "governed third-party enrichment (Apollo/Clay), fill-blanks-only",
+        summary: "governed third-party enrichment (Apollo/ZoomInfo/Clay), fill-blanks-only",
         phase: "Remediate",
         synopsis: ["fullstackgtm enrich append|refresh|ingest|status …  (run `enrich --help` for full options)"],
         detail: "Pull (Apollo) or stage (Clay) data, match it to CRM records deterministically, and emit a fill-blanks-only patch plan through the normal dry-run → approve → apply gate. `refresh` re-checks stale stamped fields.",

package/dist/cli/signals.js

@@ -171,7 +171,18 @@ from the credential ladder, never argv; --connector-opt carries non-secret knobs
             await store.appendRun({ id: signalRunId(runLabel), runLabel, startedAt: now.toISOString(), completedAt: new Date().toISOString(),
                 buckets: ["job"], counts: { fetched: discovered.summary.rawResults, new: ranked.length, deduped: deduped.length }, signals: ranked });
             console.error(`Saved signal run "${runLabel}". Next: \`fullstackgtm icp judge --signals-from ${runLabel} --save\`.`);
-            await mirrorSignalRun(runLabel, now, ["job"], { fetched: discovered.summary.rawResults, new: ranked.length, deduped: deduped.length }, ranked, rest);
+            await mirrorSignalRun(runLabel, now, ["job"], { fetched: discovered.summary.rawResults, new: ranked.length, deduped: deduped.length }, ranked, rest, {
+                provider: discovered.summary.provider,
+                searchesUsed: discovered.summary.searchesUsed,
+                searchLimit: maxSearches,
+                rawResults: discovered.summary.rawResults,
+                matchedEvidence: discovered.summary.matchedEvidence,
+                resolvedAccounts: discovered.summary.resolvedAccounts,
+                unresolvedAccounts: discovered.summary.unresolvedAccounts,
+                costUsd: discovered.summary.costUsd,
+                costLimitUsd: maxUsd,
+                warnings: discovered.summary.warnings,
+            });
         }
         else {
             console.error("(not saved — re-run with --save to persist this evidence to the signal ledger)");
@@ -389,12 +400,12 @@ from the credential ladder, never argv; --connector-opt carries non-secret knobs
     }
     throw unknownSubcommandError("signals", sub, ["fetch", "discover", "list", "outcome", "weights"]);
 }
-async function mirrorSignalRun(runLabel, startedAt, buckets, counts, signals, args) {
+async function mirrorSignalRun(runLabel, startedAt, buckets, counts, signals, args, discovery) {
     const icpPath = resolve(process.cwd(), option(args, "--icp") ?? "icp.json");
     const tracked = existsSync(icpPath) ? readIcpSyncState(icpPath) : null;
     const mirrored = await writeHostedArtifact({
         kind: "signal_run", key: `signals:${signalRunId(runLabel)}`, label: runLabel,
-        document: { runLabel, startedAt: startedAt.toISOString(), completedAt: new Date().toISOString(), buckets, counts, signals,
+        document: { runLabel, startedAt: startedAt.toISOString(), completedAt: new Date().toISOString(), buckets, counts, signals, ...discovery,
             icpRef: tracked ? { artifactId: tracked.artifactId, domain: tracked.domain, revision: tracked.revision, localIcpSha256: tracked.localIcpSha256 } : undefined },
     });
     if (mirrored.status === "saved")

package/dist/enrich.d.ts

@@ -8,7 +8,7 @@ import type { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
  *
  * Every enrichment vendor ships fire-and-forget writeback — data lands without
  * a diff, without approval, over whatever a human typed. This layer inverts
- * that: a source (Apollo pull, Clay ingest) feeds a deterministic matcher,
+ * that: a source (Apollo/ZoomInfo pull, Clay ingest) feeds a deterministic matcher,
  * the matcher feeds a fill-blanks-only patch plan, and the plan goes through
  * the existing dry-run → approval → apply contract. Every proposed value is
  * traceable to the source payload that produced it (`GtmEvidence` on the

package/dist/enrich.js

@@ -13,7 +13,7 @@ const MATCH_KEYS = {
     contact: ["email", "name", "linkedin"],
 };
 /** API source ids the MVP can pull from. */
-export const SUPPORTED_API_SOURCES = ["apollo", "explorium", "pipe0", "clay", "linkedin"];
+export const SUPPORTED_API_SOURCES = ["apollo", "zoominfo", "explorium", "pipe0", "clay", "linkedin"];
 /**
  * Canonical fields enrich may target, plus the HubSpot property spellings the
  * config may use for them (so `"crm": "numberofemployees"` and

package/dist/enrichZoomInfo.d.ts

@@ -0,0 +1,33 @@
+import type { EnrichObjectType } from "./enrich.ts";
+import type { ApolloPullKey as EnrichPullKey, ApolloPullOptions as EnrichPullOptions, ApolloPullResult as EnrichPullResult } from "./enrichApollo.ts";
+/**
+ * ZoomInfo source adapter for governed enrichment.
+ *
+ * ZoomInfo owns authentication and credit accounting in its official `gtm`
+ * CLI. fullstackgtm invokes that CLI as a read-only source, normalizes the
+ * JSON response, then sends proposed CRM changes through the normal
+ * diff → patch plan → approval → apply lifecycle. No ZoomInfo credential is
+ * copied into fullstackgtm and this adapter never writes to the CRM directly.
+ */
+export type ZoomInfoCommandResult = {
+    stdout: string;
+    stderr: string;
+};
+export type ZoomInfoCommandRunner = (executable: string, args: string[]) => Promise<ZoomInfoCommandResult>;
+export type ZoomInfoClientOptions = {
+    /** Official ZoomInfo CLI executable. Defaults to `gtm`. */
+    executable?: string;
+    /** Injectable command runner for tests. */
+    run?: ZoomInfoCommandRunner;
+};
+export type ZoomInfoClient = {
+    enrichCompany(domain: string): Promise<unknown>;
+    enrichContact(email: string): Promise<unknown>;
+};
+export declare function createZoomInfoClient(options?: ZoomInfoClientOptions): ZoomInfoClient;
+/** Pull snapshot-driven enrichment keys through ZoomInfo's official CLI. */
+export declare function pullZoomInfoRecords(client: ZoomInfoClient, keys: EnrichPullKey[], options?: EnrichPullOptions): Promise<EnrichPullResult>;
+export type ZoomInfoPullKey = EnrichPullKey;
+export type ZoomInfoPullOptions = EnrichPullOptions;
+export type ZoomInfoPullResult = EnrichPullResult;
+export type ZoomInfoObjectType = EnrichObjectType;

package/dist/enrichZoomInfo.js

@@ -0,0 +1,144 @@
+import { execFile } from "node:child_process";
+const DEFAULT_MAX_BUFFER = 16 * 1024 * 1024;
+const runCommand = (executable, args) => new Promise((resolve, reject) => {
+    execFile(executable, args, { encoding: "utf8", maxBuffer: DEFAULT_MAX_BUFFER }, (error, stdout, stderr) => {
+        if (error) {
+            const code = error.code;
+            if (code === "ENOENT") {
+                reject(new Error("ZoomInfo CLI not found. Install it with `brew install zoominfo/gtm-ai/gtm-ai-cli` " +
+                    "or `npm install -g @zoominfo/gtm-ai-cli`, then run `gtm auth login`."));
+                return;
+            }
+            // Do not echo stdout/stderr: provider errors can contain submitted
+            // company domains, contact emails, or tenant-specific data and this
+            // message may be persisted in a scheduled-run record.
+            reject(new Error(`ZoomInfo CLI failed${typeof code === "string" || typeof code === "number" ? ` (${code})` : ""}. ` +
+                "Run `gtm auth whoami`, then retry the same `gtm ... enrich` command directly if needed."));
+            return;
+        }
+        resolve({ stdout, stderr });
+    });
+});
+function parseOutput(stdout) {
+    const text = stdout.trim();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error("ZoomInfo CLI returned non-JSON output. Upgrade `gtm` and verify that `gtm ... enrich -f json` works directly.");
+    }
+}
+export function createZoomInfoClient(options = {}) {
+    const executable = options.executable ?? process.env.ZOOMINFO_GTM_BIN ?? "gtm";
+    const run = options.run ?? runCommand;
+    async function invoke(args) {
+        const result = await run(executable, [...args, "-f", "json"]);
+        return parseOutput(result.stdout);
+    }
+    return {
+        enrichCompany(domain) {
+            return invoke(["companies", "enrich", "--domain", domain]);
+        },
+        enrichContact(email) {
+            return invoke(["contacts", "enrich", "--email", email]);
+        },
+    };
+}
+function recordCandidates(value) {
+    if (Array.isArray(value)) {
+        return value.filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item));
+    }
+    if (!value || typeof value !== "object")
+        return [];
+    const object = value;
+    if (Array.isArray(object.data))
+        return recordCandidates(object.data);
+    if (object.data && typeof object.data === "object")
+        return recordCandidates(object.data);
+    if (Array.isArray(object.companies))
+        return recordCandidates(object.companies);
+    if (Array.isArray(object.contacts))
+        return recordCandidates(object.contacts);
+    return [object];
+}
+function valueAt(record, paths) {
+    for (const path of paths) {
+        let current = record;
+        for (const segment of path.split(".")) {
+            if (!current || typeof current !== "object") {
+                current = undefined;
+                break;
+            }
+            current = current[segment];
+        }
+        if (typeof current === "string" && current.trim())
+            return current.trim();
+        if (typeof current === "number" && Number.isFinite(current))
+            return String(current);
+    }
+    return undefined;
+}
+function normalizeRecord(payload, key) {
+    const record = recordCandidates(payload)[0];
+    if (!record)
+        return undefined;
+    const id = valueAt(record, ["id", "attributes.id", "companyId", "personId", "attributes.companyId", "attributes.personId"]);
+    if (key.objectType === "company") {
+        return {
+            id: `zoominfo:company_${id ?? key.value}`,
+            objectType: "company",
+            keys: {
+                domain: valueAt(record, [
+                    "attributes.domain",
+                    "attributes.website",
+                    "attributes.companyWebsite",
+                    "domain",
+                    "website",
+                    "companyWebsite",
+                ]) ?? key.value,
+                name: valueAt(record, ["attributes.name", "attributes.companyName", "name", "companyName"]),
+            },
+            payload: record,
+        };
+    }
+    return {
+        id: `zoominfo:contact_${id ?? key.value}`,
+        objectType: "contact",
+        keys: {
+            email: valueAt(record, [
+                "attributes.email",
+                "attributes.emailAddress",
+                "attributes.contactEmail",
+                "email",
+                "emailAddress",
+                "contactEmail",
+            ]) ?? key.value,
+            name: valueAt(record, ["attributes.fullName", "attributes.name", "fullName", "name"]),
+        },
+        payload: record,
+    };
+}
+/** Pull snapshot-driven enrichment keys through ZoomInfo's official CLI. */
+export async function pullZoomInfoRecords(client, keys, options = {}) {
+    const records = [];
+    const misses = [];
+    const resumeIndex = options.resumeAfter ? keys.findIndex((key) => key.value === options.resumeAfter) : -1;
+    for (const key of keys.slice(resumeIndex + 1)) {
+        const payload = key.objectType === "company"
+            ? await client.enrichCompany(key.value)
+            : await client.enrichContact(key.value);
+        const record = normalizeRecord(payload, key);
+        if (record)
+            records.push(record);
+        else
+            misses.push(key);
+        await options.onProgress?.({
+            lastKeyValue: key.value,
+            record,
+            miss: record ? undefined : key,
+        });
+    }
+    return { records, misses };
+}

package/dist/index.d.ts

@@ -28,6 +28,7 @@ export { claimHostedPlanApply, hostedPlanDigest, hostedReviewDocument, readHoste
 export { scaffoldWorkspace, starterEnrichConfig, starterIcp, starterPlaybook, type InitProvider, type InitSource, type ScaffoldFile, type ScaffoldOptions, } from "./init.ts";
 export { appendCoverage, classifyAccount, classifyCoverage, computeCoverage, coverageCountsFromSnapshot, coveredAccounts, coverageToText, crmCheckableCriteria, deriveAcvFromClosedWon, deriveBuyersPerAccount, estimateTam, loadTamModel, projectEta, readCoverageTimeline, saveTamModel, tamDir, tamReportToMarkdown, type AccountTamClass, type AcvBasis, type DerivedAcv, type DerivedBuyers, type EstimateTamInput, type TamClassified, type TamCoverage, type TamCoverageCounts, type TamCrossCheck, type TamEta, type TamModel, type TamTargeting, type TamUniverse, } from "./tam.ts";
 export { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords, type ApolloClient, type ApolloClientOptions, type ApolloPullKey, type ApolloPullResult, } from "./enrichApollo.ts";
+export { createZoomInfoClient, pullZoomInfoRecords, type ZoomInfoClient, type ZoomInfoClientOptions, type ZoomInfoCommandResult, type ZoomInfoCommandRunner, type ZoomInfoPullKey, type ZoomInfoPullOptions, type ZoomInfoPullResult, } from "./enrichZoomInfo.ts";
 export { diffFindings, diffSnapshots, diffToMarkdown, type CollectionDiff, type FieldChange, type FindingsDrift, type RecordChange, type SnapshotDiff, } from "./diff.ts";
 export { mergeSnapshots, type MergeConflict, type MergeMatch, type MergeReport, type MergeSuggestion, } from "./merge.ts";
 export { createFilePlanStore, type PlanStore, type StoredPlan } from "./planStore.ts";

package/dist/index.js

@@ -28,6 +28,7 @@ export { claimHostedPlanApply, hostedPlanDigest, hostedReviewDocument, readHoste
 export { scaffoldWorkspace, starterEnrichConfig, starterIcp, starterPlaybook, } from "./init.js";
 export { appendCoverage, classifyAccount, classifyCoverage, computeCoverage, coverageCountsFromSnapshot, coveredAccounts, coverageToText, crmCheckableCriteria, deriveAcvFromClosedWon, deriveBuyersPerAccount, estimateTam, loadTamModel, projectEta, readCoverageTimeline, saveTamModel, tamDir, tamReportToMarkdown, } from "./tam.js";
 export { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords, } from "./enrichApollo.js";
+export { createZoomInfoClient, pullZoomInfoRecords, } from "./enrichZoomInfo.js";
 export { diffFindings, diffSnapshots, diffToMarkdown, } from "./diff.js";
 export { mergeSnapshots, } from "./merge.js";
 export { createFilePlanStore } from "./planStore.js";

package/dist/runReport.js

@@ -85,6 +85,10 @@ let inflightHeartbeat = null;
  * commands simply never stream.
  */
 export function beginRunReport(args, startedAt) {
+    counts = undefined;
+    findings = undefined;
+    crm = undefined;
+    events.length = 0;
     lastHeartbeatAt = 0;
     heartbeatBroker = undefined;
     inflightHeartbeat = null;
@@ -186,6 +190,13 @@ export async function flushRunReport(args, status, startedAt, error) {
     const identity = runIdentity(args, startedAt);
     if (!identity)
         return;
+    // A successful command with no result, finding, event, or live progress is
+    // terminal telemetry rather than something a person can explore. Keep it
+    // out of Runs. Errors always report; heartbeating commands still send their
+    // terminal status so an in-progress row cannot be stranded.
+    const hasUsefulOutput = Boolean((counts && Object.keys(counts).length > 0) || findings?.length || events.length);
+    if (status === "success" && !hasUsefulOutput && lastHeartbeatAt === 0)
+        return;
     const broker = getCredential("broker");
     if (!broker?.baseUrl || !broker.accessToken)
         return; // opt-in: only when paired

package/docs/api.md

@@ -126,7 +126,7 @@ Four flags name "where data comes from / goes to"; they are not interchangeable:
 | Flag | Meaning | Values |
 |---|---|---|
 | `--provider` | The CRM the data lives in — the system a snapshot is read from and an approved plan is applied to. | `hubspot`, `salesforce` (plus `stripe`, read-only) |
-| `--source` | The external data source feeding a verb: an enrichment/discovery vendor on `enrich`/`tam` (`--source apollo`, `acquire --source pipe0`), a staged-ingest label on `enrich ingest`, on `signals fetch` which no-auth ATS board adapters to scan, or `exa` on `signals discover`. | `apollo`, `clay`, `pipe0`, `explorium`, `theirstack`, `linkedin` (HeyReach), `exa`; `greenhouse` / `lever` / `ashby` on `signals fetch` |
+| `--source` | The external data source feeding a verb: an enrichment/discovery vendor on `enrich`/`tam` (`--source zoominfo`, `--source apollo`, `acquire --source pipe0`), a staged-ingest label on `enrich ingest`, on `signals fetch` which no-auth ATS board adapters to scan, or `exa` on `signals discover`. | `zoominfo` (official `gtm` CLI), `apollo`, `clay`, `pipe0`, `explorium`, `theirstack`, `linkedin` (HeyReach), `exa`; `greenhouse` / `lever` / `ashby` on `signals fetch` |
 | `--connector` | A signal-intake source connector on `signals fetch`: pulls candidate signals from a connected platform or the local webhook spool into the signal ledger. | `file`, `serpapi-news`, `hubspot-forms` |
 | `--channel` | Where a plan's output is delivered. On `apply`, the delivery terminus — a plan applies to `--provider <crm>` *or* `--channel outbox` (render approved openers to a local outbox file; transmits nothing), never both. On `draft`, which outreach channel the opener is drafted for (shapes the emitted op). | `apply`: `outbox` · `draft`: `email`, `linkedin`, `task` |
 

package/llms.txt

@@ -149,8 +149,9 @@ approve → apply.
 
 ## Key invariants (enrich)
 
-`fullstackgtm enrich` is governed enrichment: `append` pulls (Apollo, BYO key
-via `login apollo`/APOLLO_API_KEY) or reads data staged by `ingest` (Clay CSV
+`fullstackgtm enrich` is governed enrichment: `append` pulls from Apollo (BYO key
+via `login apollo`/APOLLO_API_KEY) or ZoomInfo (official `gtm` CLI; `gtm auth login`),
+or reads data staged by `ingest` (Clay CSV
 exports / webhook payload JSON), matches source records to CRM records via
 ordered keys in `enrich.config.json` (unique hit wins; ambiguity skips or
 becomes `requires_human_record_selection` placeholders — never a coin flip),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fullstackgtm",
-  "version": "0.57.0",
-  "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
+  "version": "0.58.0",
+  "description": "Open-source CRM control plane and safety toolbox for AI agents: deterministic audits, reviewable patch plans, approval-gated write-back, conflict detection, and entity resolution for HubSpot and Salesforce.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM LLC <ryan@fullstackgtm.com> (https://fullstackgtm.com)",
   "homepage": "https://github.com/fullstackgtm/core#readme",

package/src/cli/enrich.ts

@@ -19,7 +19,8 @@ import { progressReporter, reportCounts, reportEvent } from "../runReport.ts";
 import { ACQUIRE_STAGES, composeListeners, createProgressEmitter } from "../progress.ts";
 import { createLinkedInProvider, discoverLinkedInProspects } from "../acquireLinkedIn.ts";
 import { clayPeopleFilterRoutes, fitThreshold, icpToClayInvestmentCompanyFilters, icpToClayPeopleFilters, icpToCrustdataFilters, icpToExploriumFilters, scoreProspectAgainstIcp, type Icp } from "../icp.ts";
-import { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords, type ApolloPullKey } from "../enrichApollo.ts";
+import { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords, type ApolloPullKey, type ApolloPullOptions } from "../enrichApollo.ts";
+import { createZoomInfoClient, pullZoomInfoRecords } from "../enrichZoomInfo.ts";
 import type { CanonicalGtmSnapshot, CreateRecordPayload } from "../types.ts";
 import { isSpoolPath, readSpoolPath } from "../spoolFiles.ts";
 import { isOptionValue, loadIcp, numericOption, option, readSnapshot, saveRequested } from "./shared.ts";
@@ -33,8 +34,8 @@ import { readIcpSyncState } from "../icpSync.ts";
 
 
 /**
- * The enrich layer: governed append/refresh of third-party data (Apollo pull,
- * Clay ingest) into the CRM through the normal dry-run → approval → apply
+ * The enrich layer: governed append/refresh of third-party data (Apollo or
+ * ZoomInfo pull, Clay ingest) into the CRM through the normal dry-run → approval → apply
  * contract. State lives in the profile-scoped run store (checkpoint,
  * staleness ledger, observability in one); scheduling belongs to the
  * horizontal scheduler — enrich owns no cron logic.
@@ -77,8 +78,9 @@ and leaves them unassigned. Backfill existing ownerless records with
 \`reassign --assign-unowned --to <ownerId>\`.
 
 append pulls from an api source (Apollo — BYO key via \`login apollo\` or
-APOLLO_API_KEY) or reads data staged by \`enrich ingest\` (Clay CSV exports,
-webhook payload JSON), matches source records to CRM records via the ordered
+APOLLO_API_KEY; ZoomInfo — official \`gtm\` CLI via \`gtm auth login\`) or reads
+data staged by \`enrich ingest\` (Clay CSV exports, webhook payload JSON),
+matches source records to CRM records via the ordered
 match keys in enrich.config.json (unique hit wins; zero hits falls through to
 the next key; multiple hits skip or flow into the suggest chain, per
 onAmbiguous), and emits a fill-blanks-only patch plan. Without --save it
@@ -261,6 +263,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
     // piped) and, via the composed reporter, heartbeat to a paired hosted app.
     // The meter reading (creates vs headroom + budget burn) rides the same
     // emitter, feeding the dashboard's gauge without printing anything new.
+    const acquireRunLabel = option(rest, "--run-label") ?? `acquire-${source}-${today}`;
     let result: ReturnType<typeof buildAcquirePlan>;
     try {
       acquireProgress.stage(ACQUIRE_STAGES[2], 2, ACQUIRE_STAGES.length);
@@ -277,7 +280,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         source,
         snapshot,
         records,
-        runLabel: option(rest, "--run-label") ?? `acquire-${source}-${today}`,
+        runLabel: acquireRunLabel,
         maxRecords: cap,
         progress: acquireProgress,
       });
@@ -295,7 +298,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
     // Observability: headline metrics for the web run timeline (paired users).
     reportCounts({
       sourced: result.counts.fetched,
-      created: result.counts.created,
+      proposed: result.counts.created,
       withheldByMeter: result.counts.withheldByMeter,
       skippedInCrm: apiSkippedCrm,
       skippedSeen: apiSkippedSeen,
@@ -307,9 +310,9 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
     const icpPath = resolve(process.cwd(), option(rest, "--icp") ?? "icp.json");
     const trackedIcp = existsSync(icpPath) ? readIcpSyncState(icpPath) : null;
     const leadMirror = await writeHostedArtifact({
-      kind: "lead_run", key: `leads:${result.plan.id}`, label: result.plan.title ?? result.plan.id,
+      kind: "lead_run", key: `leads:${result.plan.id}`, label: acquireRunLabel,
       domain: trackedIcp?.domain,
-      document: { runLabel: result.plan.id, createdAt: new Date().toISOString(), source, counts: result.counts,
+      document: { runLabel: acquireRunLabel, createdAt: new Date().toISOString(), source, targetDomain: option(rest, "--company-domain"), counts: result.counts,
         plan: result.plan, icpRef: trackedIcp ? { artifactId: trackedIcp.artifactId, domain: trackedIcp.domain, revision: trackedIcp.revision, localIcpSha256: trackedIcp.localIcpSha256 } : undefined },
     });
     if (leadMirror.status === "saved") console.error(`Recorded lead preview against${trackedIcp ? ` ICP revision ${trackedIcp.revision}` : " the local untracked ICP"}.`);
@@ -436,10 +439,19 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
       );
       return;
     }
-    const client = createApolloClient({
-      getApiKey: () => apolloApiKey(),
-      apiBaseUrl: process.env.APOLLO_API_BASE_URL,
-    });
+    if (source !== "apollo" && source !== "zoominfo") {
+      throw new Error(
+        `enrich ${mode}: api source "${source}" supports acquire discovery, not snapshot enrichment. ` +
+          "Use apollo or zoominfo for append/refresh, or stage records with `enrich ingest`.",
+      );
+    }
+    const apolloClient = source === "apollo"
+      ? createApolloClient({
+          getApiKey: () => apolloApiKey(),
+          apiBaseUrl: process.env.APOLLO_API_BASE_URL,
+        })
+      : null;
+    const zoomInfoClient = source === "zoominfo" ? createZoomInfoClient() : null;
     if (save) {
       run = await openEnrichRun(store, source, mode, option(rest, "--run-label"), today);
       if (run.cursor) {
@@ -455,7 +467,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
     let pullProcessed = 0;
     let result: Awaited<ReturnType<typeof pullApolloRecords>>;
     try {
-      result = await pullApolloRecords(client, pullKeys, {
+      const pullOptions: ApolloPullOptions = {
         resumeAfter: run?.cursor ?? null,
         onProgress: async (progress) => {
           if (pullBar.active) {
@@ -473,7 +485,10 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
           if (progress.miss) run.missedKeys = [...(run.missedKeys ?? []), progress.miss.value];
           await store.update(run);
         },
-      });
+      };
+      result = source === "zoominfo"
+        ? await pullZoomInfoRecords(zoomInfoClient!, pullKeys, pullOptions)
+        : await pullApolloRecords(apolloClient!, pullKeys, pullOptions);
     } finally {
       pullBar.done();
     }

package/src/cli/help.ts

@@ -90,7 +90,7 @@ Usage:
   fullstackgtm enrich refresh [--source apollo] [--stale-days <n>] [--save] [--config <path>] [source options]
   fullstackgtm enrich ingest <file.csv|payload.json|spool.jsonl|spool-dir> --source clay [--run-label <label>]
   fullstackgtm enrich status [--runs] [--source <id>] [--json]
-                                               governed enrichment: pull (Apollo) or stage (Clay) third-party
+                                               governed enrichment: pull (Apollo/ZoomInfo) or stage (Clay) third-party
                                                data, match it to CRM records deterministically, and emit a
                                                fill-blanks-only patch plan through the normal dry-run →
                                                approve → apply gate. refresh re-checks stale stamped fields
@@ -524,7 +524,7 @@ export const HELP: Record<string, HelpEntry> = {
     seeAlso: ["enrich", "plans", "apply", "resolve"],
   },
   enrich: {
-    summary: "governed third-party enrichment (Apollo/Clay), fill-blanks-only",
+    summary: "governed third-party enrichment (Apollo/ZoomInfo/Clay), fill-blanks-only",
     phase: "Remediate",
     synopsis: ["fullstackgtm enrich append|refresh|ingest|status …  (run `enrich --help` for full options)"],
     detail:

package/src/cli/signals.ts

@@ -179,7 +179,18 @@ from the credential ladder, never argv; --connector-opt carries non-secret knobs
       await store.appendRun({ id: signalRunId(runLabel), runLabel, startedAt: now.toISOString(), completedAt: new Date().toISOString(),
         buckets: ["job"], counts: { fetched: discovered.summary.rawResults, new: ranked.length, deduped: deduped.length }, signals: ranked });
       console.error(`Saved signal run "${runLabel}". Next: \`fullstackgtm icp judge --signals-from ${runLabel} --save\`.`);
-      await mirrorSignalRun(runLabel, now, ["job"], { fetched: discovered.summary.rawResults, new: ranked.length, deduped: deduped.length }, ranked, rest);
+      await mirrorSignalRun(runLabel, now, ["job"], { fetched: discovered.summary.rawResults, new: ranked.length, deduped: deduped.length }, ranked, rest, {
+        provider: discovered.summary.provider,
+        searchesUsed: discovered.summary.searchesUsed,
+        searchLimit: maxSearches,
+        rawResults: discovered.summary.rawResults,
+        matchedEvidence: discovered.summary.matchedEvidence,
+        resolvedAccounts: discovered.summary.resolvedAccounts,
+        unresolvedAccounts: discovered.summary.unresolvedAccounts,
+        costUsd: discovered.summary.costUsd,
+        costLimitUsd: maxUsd,
+        warnings: discovered.summary.warnings,
+      });
     } else {
       console.error("(not saved — re-run with --save to persist this evidence to the signal ledger)");
     }
@@ -414,12 +425,13 @@ async function mirrorSignalRun(
   counts: { fetched: number; new: number; deduped: number },
   signals: Signal[],
   args: string[],
+  discovery?: Record<string, unknown>,
 ) {
   const icpPath = resolve(process.cwd(), option(args, "--icp") ?? "icp.json");
   const tracked = existsSync(icpPath) ? readIcpSyncState(icpPath) : null;
   const mirrored = await writeHostedArtifact({
     kind: "signal_run", key: `signals:${signalRunId(runLabel)}`, label: runLabel,
-    document: { runLabel, startedAt: startedAt.toISOString(), completedAt: new Date().toISOString(), buckets, counts, signals,
+    document: { runLabel, startedAt: startedAt.toISOString(), completedAt: new Date().toISOString(), buckets, counts, signals, ...discovery,
       icpRef: tracked ? { artifactId: tracked.artifactId, domain: tracked.domain, revision: tracked.revision, localIcpSha256: tracked.localIcpSha256 } : undefined },
   });
   if (mirrored.status === "saved") console.error("Mirrored the signal run to the paired hosted workspace.");