fullstackgtm 0.34.0 → 0.38.0

package/dist/connectors/prospectSources.js

@@ -0,0 +1,227 @@
+function splitName(full) {
+    if (!full)
+        return {};
+    const parts = full.trim().split(/\s+/);
+    if (parts.length === 1)
+        return { firstName: parts[0] };
+    return { firstName: parts[0], lastName: parts.slice(1).join(" ") };
+}
+function bareDomain(value) {
+    if (!value)
+        return undefined;
+    return value
+        .trim()
+        .replace(/^https?:\/\//i, "")
+        .replace(/^www\./i, "")
+        .replace(/\/.*$/, "")
+        .toLowerCase() || undefined;
+}
+export async function fetchExploriumProspects(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const base = (opts.apiBaseUrl ?? "https://api.explorium.ai").replace(/\/$/, "");
+    const size = Math.min(opts.size ?? 25, 100);
+    const response = await fetchImpl(`${base}/v1/prospects`, {
+        method: "POST",
+        headers: { "api_key": opts.apiKey, "Content-Type": "application/json" },
+        body: JSON.stringify({ mode: "full", size, page_size: size, page: 1, filters: opts.filters }),
+    });
+    if (!response.ok) {
+        throw new Error(`Explorium /v1/prospects failed: HTTP ${response.status} ${await safeText(response)}`);
+    }
+    const data = (await response.json());
+    return (data.data ?? []).map((row) => ({
+        firstName: row.first_name,
+        lastName: row.last_name,
+        fullName: row.full_name ?? ([row.first_name, row.last_name].filter(Boolean).join(" ") || undefined),
+        jobTitle: row.job_title,
+        jobLevel: row.job_level_main,
+        jobDepartment: row.job_department_main,
+        companyName: row.company_name,
+        companyDomain: bareDomain(row.company_website),
+        linkedin: normalizeLinkedin(row.linkedin),
+        sourceId: row.prospect_id,
+    }));
+}
+// ---------------------------------------------------------------------------
+// pipe0 / Crustdata — net-new discovery (search). Crustdata is built into pipe0
+// (no separate connection needed). Returns profiles; pair with
+// pipe0ResolveWorkEmails to get real emails.
+export async function fetchPipe0CrustdataProspects(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const base = (opts.apiBaseUrl ?? "https://api.pipe0.com").replace(/\/$/, "");
+    const limit = Math.min(opts.limit ?? 25, 100);
+    const response = await fetchImpl(`${base}/v1/searches/run/sync`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${opts.apiKey}`, "Content-Type": "application/json" },
+        body: JSON.stringify({
+            searches: [{ search_id: "people:profiles:crustdata@1", config: { limit, filters: opts.filters } }],
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`pipe0 /v1/searches/run/sync failed: HTTP ${response.status} ${await safeText(response)}`);
+    }
+    const body = (await response.json());
+    // Surface upstream provider errors (e.g. CreditBalanceInsufficient) instead of
+    // silently returning [] — a throttle/credit failure must not look like "no ICP matches".
+    const upstreamErrors = (body.search_statuses ?? []).flatMap((s) => s.errors ?? []);
+    if (upstreamErrors.length > 0 && !(body.results ?? []).length) {
+        throw new Error(`pipe0/Crustdata search error: ${upstreamErrors.map((e) => `${e.code ?? "error"}: ${e.message ?? ""}`).join("; ")}`);
+    }
+    return (body.results ?? []).map((row) => {
+        const fullName = strField(row.name);
+        const { firstName, lastName } = splitName(fullName);
+        return {
+            firstName,
+            lastName,
+            fullName,
+            jobTitle: strField(row.job_title),
+            companyDomain: bareDomain(strField(row.company_website_url)),
+            linkedin: normalizeLinkedin(strField(row.profile_url)),
+            sourceId: strField(row.profile_url) ?? fullName,
+        };
+    });
+}
+function strField(field) {
+    const v = field?.value;
+    return typeof v === "string" && v.trim() ? v : undefined;
+}
+function normalizeLinkedin(value) {
+    if (!value)
+        return undefined;
+    const v = value.trim().replace(/^https?:\/\//i, "").replace(/\/$/, "");
+    return v ? `https://${v}` : undefined;
+}
+// ---------------------------------------------------------------------------
+// pipe0 — work-email resolution (waterfall)
+/**
+ * Resolve real work emails for people via pipe0's waterfall. Input rows need a
+ * full name + a company domain (or name). Returns the prospects with `email`
+ * filled where the waterfall found one; rows with no hit are returned unchanged.
+ */
+export async function pipe0ResolveWorkEmails(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const base = (opts.apiBaseUrl ?? "https://api.pipe0.com").replace(/\/$/, "");
+    const chunkSize = Math.max(1, opts.chunkSize ?? 3);
+    // Only rows with the waterfall's required inputs (name + company_domain|name).
+    const resolvable = opts.prospects.filter((p) => p.fullName && (p.companyDomain || p.companyName));
+    if (resolvable.length === 0)
+        return opts.prospects;
+    const emailByKey = new Map();
+    for (let i = 0; i < resolvable.length; i += chunkSize) {
+        const chunk = resolvable.slice(i, i + chunkSize);
+        const input = chunk.map((p) => ({
+            name: p.fullName,
+            ...(p.companyDomain ? { company_domain: p.companyDomain } : { company_name: p.companyName }),
+        }));
+        let body;
+        try {
+            const response = await fetchImpl(`${base}/v1/pipes/run/sync`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${opts.apiKey}`, "Content-Type": "application/json" },
+                body: JSON.stringify({ pipes: [{ pipe_id: "person:workemail:waterfall@1" }], input }),
+            });
+            if (!response.ok)
+                continue; // throttled/5xx chunk — skip, keep the rest
+            body = (await response.json());
+        }
+        catch {
+            continue; // network hiccup on one chunk must not sink the whole run
+        }
+        for (const recordId of body.order ?? []) {
+            const fields = body.records?.[recordId]?.fields ?? {};
+            const email = fields.work_email?.status === "completed" ? fieldValue(fields.work_email) : undefined;
+            if (email) {
+                const domain = fieldValue(fields.company_domain) ?? fieldValue(fields.company_name);
+                emailByKey.set(personKey(fieldValue(fields.name), domain), email);
+            }
+        }
+    }
+    return opts.prospects.map((p) => {
+        const email = emailByKey.get(personKey(p.fullName, p.companyDomain ?? p.companyName));
+        return email ? { ...p, email } : p;
+    });
+}
+function personKey(name, company) {
+    return `${(name ?? "").trim().toLowerCase()}|${(company ?? "").trim().toLowerCase()}`;
+}
+function fieldValue(field) {
+    const v = field?.value;
+    return typeof v === "string" && v.trim() ? v : undefined;
+}
+async function safeText(response) {
+    try {
+        return (await response.text()).slice(0, 300);
+    }
+    catch {
+        return "";
+    }
+}
+// ---------------------------------------------------------------------------
+// Pre-email 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, " ");
+}
+/**
+ * Stable identity keys for a prospect (prefixed by kind). A match on ANY key
+ * means "same person". LinkedIn is strongest; name+domain is the only key
+ * shareable with the canonical CRM snapshot (which has no LinkedIn); email is
+ * available only after resolution (so it can't pre-filter, but it strengthens
+ * the seen cache).
+ */
+export function prospectIdentityKeys(p) {
+    const keys = [];
+    if (p.linkedin)
+        keys.push(`li:${p.linkedin.trim().toLowerCase().replace(/\/+$/, "")}`);
+    const name = normName(p.fullName ?? [p.firstName, p.lastName].filter(Boolean).join(" "));
+    const domain = bareDomain(p.companyDomain);
+    if (name && domain)
+        keys.push(`nd:${name}|${domain}`);
+    if (p.email)
+        keys.push(`em:${p.email.trim().toLowerCase()}`);
+    return keys;
+}
+/** Identity keys for every contact already in the CRM snapshot (email + name|domain). */
+export function crmContactKeys(snapshot) {
+    const domainByAccount = new Map();
+    for (const account of snapshot.accounts ?? []) {
+        const d = bareDomain(account.domain);
+        if (d)
+            domainByAccount.set(account.id, d);
+    }
+    const set = new Set();
+    for (const contact of snapshot.contacts ?? []) {
+        if (contact.linkedin)
+            set.add(`li:${contact.linkedin.trim().toLowerCase().replace(/\/+$/, "")}`);
+        if (contact.email)
+            set.add(`em:${contact.email.trim().toLowerCase()}`);
+        const name = normName([contact.firstName, contact.lastName].filter(Boolean).join(" "));
+        const domain = contact.accountId ? domainByAccount.get(contact.accountId) : undefined;
+        if (name && domain)
+            set.add(`nd:${name}|${domain}`);
+    }
+    return set;
+}
+/**
+ * Split prospects into those worth paying to enrich vs. drop. A prospect is
+ * dropped if any identity key is already in the CRM (`crmKeys`) or in the
+ * cross-run `seen` cache. Pure + deterministic.
+ */
+export function partitionFreshProspects(prospects, crmKeys, seen) {
+    const fresh = [];
+    let skippedCrm = 0;
+    let skippedSeen = 0;
+    for (const p of prospects) {
+        const keys = prospectIdentityKeys(p);
+        if (keys.some((k) => crmKeys.has(k))) {
+            skippedCrm += 1;
+            continue;
+        }
+        if (keys.some((k) => seen.has(k))) {
+            skippedSeen += 1;
+            continue;
+        }
+        fresh.push(p);
+    }
+    return { fresh, skippedCrm, skippedSeen };
+}

package/dist/enrich.d.ts

@@ -1,3 +1,5 @@
+import type { AcquireBudget } from "./acquireMeter.ts";
+import type { AssignmentContext, AssignmentPolicy } from "./assign.ts";
 import type { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
 /**
  * The enrich layer: governed append/refresh of third-party data into the CRM.
@@ -55,6 +57,47 @@ export type EnrichConfig = {
     match: Partial<Record<EnrichObjectType, EnrichMatchConfig>>;
     fields: Partial<Record<EnrichObjectType, EnrichFieldConfig[]>>;
     policy: EnrichPolicyConfig;
+    /** Net-new lead creation (`enrich acquire`). Optional; absent = acquire off. */
+    acquire?: AcquireConfig;
+};
+/** Maps a sourced record to the CRM properties a net-new record is created with. */
+export type AcquireCreateMap = {
+    /** CRM property name → source payload path (read via sourceValueAt). */
+    properties: Record<string, string>;
+    /** Source path whose value becomes the dedupe key (e.g. "email"). */
+    matchKey: string;
+    /** Optional source path to a company name; the connector resolves-or-creates it. */
+    associateCompanyFrom?: string;
+};
+/**
+ * Net-new discovery for an API acquire source. `provider` selects the adapter
+ * (explorium = prospect search; pipe0 = work-email waterfall). `filters` is the
+ * provider-native query; `resolveEmailsWith` chains a second provider to fill
+ * real emails (e.g. explorium discovers, pipe0 resolves the work email).
+ */
+export type AcquireDiscoveryConfig = {
+    provider: "explorium" | "pipe0" | "linkedin" | "heyreach";
+    filters?: Record<string, unknown>;
+    size?: number;
+    resolveEmailsWith?: "pipe0";
+    /** LinkedIn sources only: the provider-native list id to read (HeyReach lead-list id). */
+    listId?: string;
+};
+export type AcquireConfig = {
+    /** Windowed budget enforced by the acquire meter; absent = unmetered. */
+    budget?: AcquireBudget;
+    /** Estimated provider cost (USD) per created record, by source id. */
+    costPerRecord?: Record<string, number>;
+    /** How to build a net-new record from a sourced row, per object type. */
+    create: Partial<Record<EnrichObjectType, AcquireCreateMap>>;
+    /** Net-new discovery params for API sources, by source id. */
+    discovery?: Record<string, AcquireDiscoveryConfig>;
+    /**
+     * Ownership rule stamped onto every created lead so it is never born
+     * ownerless. Absent = no auto-assignment (the CLI may still default to the
+     * portal's sole active owner). Shared with `reassign --assign-unowned`.
+     */
+    assign?: AssignmentPolicy;
 };
 export declare const ENRICH_CONFIG_FILE_NAME = "enrich.config.json";
 export declare const DEFAULT_STALE_DAYS = 90;
@@ -68,6 +111,25 @@ export declare function resolveCrmField(objectType: EnrichObjectType, name: stri
  * the accepted values.
  */
 export declare function parseEnrichConfig(raw: string): EnrichConfig;
+/**
+ * Built-in zero-config presets for well-known sources, so the common Mode-A
+ * loop — "feed a Clay export, get the dedup/routing verdict" — needs no
+ * hand-authored config. These are **match-only** (empty `fields`): the value is
+ * the matched / unmatched / ambiguous routing and collision detection, not field
+ * writes. Drop an `enrich.config.json` next to your run to map fields for actual
+ * field enrichment; an explicit config always wins over a preset. Constructed
+ * directly (not via `parseEnrichConfig`) so the match-only shape is allowed.
+ */
+export declare const BUILTIN_ENRICH_PRESETS: Record<string, EnrichConfig>;
+export declare function builtinEnrichPreset(source: string | undefined): EnrichConfig | undefined;
+/**
+ * Zero-config `enrich acquire` preset so every client gets targeted, deduped,
+ * metered lead-fill out of the box — no hand-authored enrich.config.json. The
+ * ICP (icp.json) supplies the targeting; this supplies sensible plumbing. The
+ * create mapping writes the prospect's LinkedIn URL into hs_linkedin_url, so
+ * each created contact strengthens future dedup. An explicit config always wins.
+ */
+export declare function builtinAcquirePreset(source: string | undefined): EnrichConfig | undefined;
 export declare function loadEnrichConfig(path: string): EnrichConfig;
 export declare function parseCsv(text: string): Array<Record<string, string>>;
 export type EnrichSourceRecord = {
@@ -154,6 +216,51 @@ export type EnrichPlanResult = {
  * current CRM value → apply-time compare-and-set rejects drifted records).
  */
 export declare function buildEnrichPlan(options: BuildEnrichPlanOptions): EnrichPlanResult;
+export type AcquireCounts = {
+    fetched: number;
+    matched: number;
+    ambiguous: number;
+    unmatched: number;
+    /** create_record ops emitted. */
+    created: number;
+    /** unmatched rows that would have been created but for the meter ceiling. */
+    withheldByMeter: number;
+    /** created ops that got an owner stamped (a subset of `created`). */
+    assigned: number;
+    /** created ops left ownerless (no policy, or policy could not place them). */
+    unassigned: number;
+};
+export type AcquirePlanResult = {
+    plan: PatchPlan;
+    counts: AcquireCounts;
+    estCostUsd: number;
+};
+export type BuildAcquirePlanOptions = {
+    config: EnrichConfig;
+    source: string;
+    snapshot: CanonicalGtmSnapshot;
+    records: EnrichSourceRecord[];
+    runLabel: string;
+    /** Meter ceiling: max create ops to emit. null/undefined = unlimited. */
+    maxRecords?: number | null;
+    now?: () => Date;
+};
+/**
+ * Lift a prospect/source payload into the routing attributes a territory rule
+ * reads. Tolerant of provider spellings (explorium vs pipe0); absent attributes
+ * stay undefined, so a rule that routes on them simply won't match (falling to
+ * the policy fallback) instead of mis-routing.
+ */
+export declare function acquireAssignmentContext(payload: Record<string, unknown>, companyName: string | undefined, accountOwnerByName: ReadonlyMap<string, string>): AssignmentContext;
+/**
+ * Match each sourced record against the snapshot and route it: matched =
+ * already in the CRM (skip), ambiguous = a possible duplicate exists (skip —
+ * resolve-first never creates over ambiguity), unmatched = a net-new lead.
+ * Unmatched rows with a dedupe key and at least one mapped property become
+ * `create_record` operations, capped at `maxRecords` (the meter's headroom).
+ * Always a dry-run plan; nothing is written until apply.
+ */
+export declare function buildAcquirePlan(options: BuildAcquirePlanOptions): AcquirePlanResult;
 /** Latest stamp per (objectType, objectId, field) across a source's runs. */
 export declare function latestStamps(runs: EnrichRun[], source: string): Map<string, EnrichStamp>;
 export declare function staleDaysFor(config: EnrichConfig, objectType: EnrichObjectType, field: string): number;