fullstackgtm 0.34.0 → 0.38.0

package/dist/connectors/hubspot.js

@@ -26,6 +26,10 @@ export function createHubspotConnector(options) {
     // search API is eventually consistent, so a just-created company is
     // invisible to search — this map is the authoritative same-run record.
     const createdCompaniesByName = new Map();
+    // Same-run dedup for `create_record` contact creates, keyed by lowercased
+    // match value (email): HubSpot search is eventually consistent, so a contact
+    // created earlier in this apply run is invisible to a later search.
+    const createdContactsByMatch = new Map();
     async function request(path, init = {}) {
         const token = await options.getAccessToken();
         let response;
@@ -161,6 +165,7 @@ export function createHubspotConnector(options) {
                 email: stringOrUndefined(readMapped(props, "contacts", "email", "email")),
                 phone: stringOrUndefined(readMapped(props, "contacts", "phone", "phone")),
                 title: stringOrUndefined(readMapped(props, "contacts", "title", "jobtitle")),
+                linkedin: stringOrUndefined(readMapped(props, "contacts", "linkedin", "hs_linkedin_url")),
                 ownerId: stringOrUndefined(readMapped(props, "contacts", "ownerId", "hubspot_owner_id")),
                 provenance: provenanceFrom(props),
                 lastSyncAt: stringOrUndefined(contact.updatedAt),
@@ -413,6 +418,139 @@ export function createHubspotConnector(options) {
         });
         return (data?.results ?? []).map((row) => String(row.id));
     }
+    /** Exact-value contact lookup (by any searchable property) for resolve-first creates. */
+    async function searchContactsBy(property, value) {
+        const data = await request(`/crm/v3/objects/contacts/search`, {
+            method: "POST",
+            body: JSON.stringify({
+                filterGroups: [{ filters: [{ propertyName: property, operator: "EQ", value }] }],
+                properties: [property],
+                limit: 3,
+            }),
+        });
+        return (data?.results ?? []).map((row) => String(row.id));
+    }
+    /**
+     * Resolve a company by exact name, creating it on a confirmed miss. Returns
+     * the company id, or null on ambiguity (≥2 existing) so the caller skips the
+     * association rather than guessing. Same-run safe via createdCompaniesByName.
+     */
+    async function resolveOrCreateCompanyByName(name, opId) {
+        const nameKey = name.toLowerCase();
+        const already = createdCompaniesByName.get(nameKey);
+        if (already)
+            return already;
+        const matches = await searchCompaniesByName(name);
+        if (matches.length > 1)
+            return null;
+        if (matches.length === 1) {
+            createdCompaniesByName.set(nameKey, matches[0]);
+            return matches[0];
+        }
+        let created;
+        try {
+            created = await request(`/crm/v3/objects/companies`, {
+                method: "POST",
+                body: JSON.stringify({
+                    properties: { name, hs_object_source_detail_2: `fullstackgtm acquire (${opId})` },
+                }),
+            });
+        }
+        catch {
+            created = await request(`/crm/v3/objects/companies`, {
+                method: "POST",
+                body: JSON.stringify({ properties: { name } }),
+            });
+        }
+        const id = String(created.id);
+        createdCompaniesByName.set(nameKey, id);
+        return id;
+    }
+    /**
+     * Create a NET-NEW record (a sourced lead). Resolve-first: re-checks the
+     * dedupe key against the live CRM (the plan-time snapshot can be stale) and
+     * creates ONLY on a confirmed miss — a record a concurrent writer already
+     * added is returned as `skipped`, never duplicated. Contacts can be linked
+     * to a resolved-or-created company in the same step.
+     */
+    async function createRecord(operation) {
+        const payload = operation.afterValue;
+        if (!payload || typeof payload !== "object" || !payload.properties) {
+            return { operationId: operation.id, status: "skipped", detail: "create_record needs a CreateRecordPayload afterValue." };
+        }
+        const objectPath = OBJECT_PATHS[operation.objectType];
+        if (operation.objectType !== "contact" && operation.objectType !== "account") {
+            return { operationId: operation.id, status: "skipped", detail: "create_record supports contacts and accounts." };
+        }
+        const matchValue = String(payload.matchValue ?? "").trim();
+        if (!matchValue) {
+            return { operationId: operation.id, status: "skipped", detail: "create_record needs a non-empty matchValue to resolve-first." };
+        }
+        if (operation.objectType === "account") {
+            const id = await resolveOrCreateCompanyByName(matchValue, operation.id);
+            if (id === null) {
+                return { operationId: operation.id, status: "skipped", detail: `create_record: ambiguous — multiple companies named "${matchValue}". Not creating.` };
+            }
+            return { operationId: operation.id, status: "applied", detail: `Resolved/created company "${matchValue}" (${id}).`, providerData: { id } };
+        }
+        // contact — resolve-first on the dedupe key (email by default)
+        const matchKey = payload.matchKey || "email";
+        const matchKeyLower = `${matchKey}:${matchValue.toLowerCase()}`;
+        if (createdContactsByMatch.has(matchKeyLower)) {
+            return { operationId: operation.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already created earlier in this run; not duplicating.`, providerData: { id: createdContactsByMatch.get(matchKeyLower), existing: true } };
+        }
+        const existing = await searchContactsBy(matchKey, matchValue);
+        if (existing.length > 0) {
+            createdContactsByMatch.set(matchKeyLower, existing[0]);
+            return { operationId: operation.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already exists (${existing.join(", ")}); resolve-first declined to create.`, providerData: { id: existing[0], existing: true } };
+        }
+        const properties = { ...payload.properties };
+        // Stamp ownership at create time so the lead is never born ownerless. The
+        // canonical ownerId maps to HubSpot's standard owner property.
+        if (payload.ownerId && !properties.hubspot_owner_id) {
+            properties.hubspot_owner_id = String(payload.ownerId);
+        }
+        let created;
+        try {
+            created = await request(`/crm/v3/objects/${objectPath}`, {
+                method: "POST",
+                body: JSON.stringify({ properties: { ...properties, hs_object_source_detail_2: `fullstackgtm acquire (${operation.id})` } }),
+            });
+        }
+        catch {
+            // Some portals reject writes to source-detail properties — the provenance
+            // stamp is best-effort, the create is not.
+            created = await request(`/crm/v3/objects/${objectPath}`, {
+                method: "POST",
+                body: JSON.stringify({ properties }),
+            });
+        }
+        const contactId = String(created.id);
+        createdContactsByMatch.set(matchKeyLower, contactId);
+        let companyNote = "";
+        if (payload.associateCompanyName) {
+            try {
+                const companyId = await resolveOrCreateCompanyByName(payload.associateCompanyName, operation.id);
+                if (companyId) {
+                    await request(`/crm/v4/objects/contacts/${encodeURIComponent(contactId)}/associations/default/companies/${encodeURIComponent(companyId)}`, { method: "PUT" });
+                    companyNote = ` Linked to company "${payload.associateCompanyName}" (${companyId}).`;
+                }
+                else {
+                    companyNote = ` Company "${payload.associateCompanyName}" was ambiguous; left unlinked.`;
+                }
+            }
+            catch (error) {
+                // Association is best-effort — the contact create already succeeded.
+                companyNote = ` (company link failed: ${error instanceof Error ? error.message : String(error)})`;
+            }
+        }
+        return {
+            operationId: operation.id,
+            status: "applied",
+            detail: `Created contact ${matchKey}=${matchValue} (${contactId}).${companyNote}`,
+            providerData: { id: contactId, created: true },
+        };
+    }
     async function createTask(operation) {
         const associationTypeId = TASK_ASSOCIATION_TYPE_IDS[operation.objectType];
         if (associationTypeId === undefined) {
@@ -602,6 +740,8 @@ export function createHubspotConnector(options) {
                     return await linkRecord(operation);
                 case "create_task":
                     return await createTask(operation);
+                case "create_record":
+                    return await createRecord(operation);
                 case "merge_records":
                     return await mergeRecords(operation);
                 case "archive_record":

package/dist/connectors/linkedin.d.ts

@@ -0,0 +1,78 @@
+/**
+ * LinkedIn connector — Phase 1 discovery (read-only).
+ *
+ * A provider-agnostic surface for pulling prospects out of LinkedIn via a
+ * rented execution layer (default: HeyReach; Unipile is a drop-in alternative).
+ * Deliberately decoupled from the acquire spine — the `Icp`→filter and
+ * `LinkedInProspect`→`Prospect` bridges live in the `enrich acquire --source
+ * linkedin` wiring, not here — so this layer can land and be tested on its own.
+ *
+ * Phase 2 (future) extends `LinkedInProvider` with send actions
+ * (connect/message) routed through the plan/apply gate. Spec:
+ * docs/linkedin-connector-spec.md. Nothing here ever writes or sends.
+ */
+export type LinkedInProspect = {
+    firstName: string;
+    lastName: string;
+    fullName?: string;
+    headline?: string;
+    jobTitle?: string;
+    company?: string;
+    /** Canonical LinkedIn profile URL — the identity key dedup uses downstream. */
+    profileUrl: string;
+    location?: string;
+    email?: string;
+    emailStatus?: string;
+    /** The raw provider payload, preserved for debugging and later mapping. */
+    raw?: unknown;
+};
+export type LinkedInSource = {
+    /** Provider-native id of a prospect source (HeyReach: a lead-list id). */
+    id: string;
+    name: string;
+    /** Approximate prospect count, when the provider reports it. */
+    count?: number;
+};
+export type FetchProspectsOptions = {
+    /** Which source to read (HeyReach lead-list id); provider may have a default. */
+    sourceId?: string;
+    /** Hard cap on prospects returned; also bounds pagination. */
+    max?: number;
+};
+export type ConnectionStatus = {
+    ok: boolean;
+    detail: string;
+};
+/**
+ * Provider-agnostic LinkedIn discovery surface (Phase 1). Read-only: it
+ * enumerates prospect sources and pulls normalized prospects, never sends.
+ */
+export interface LinkedInProvider {
+    readonly name: string;
+    /** Cheap auth/connectivity check; never throws — returns ok:false instead. */
+    checkConnection(): Promise<ConnectionStatus>;
+    /** Enumerate prospect sources (HeyReach lead lists). */
+    listSources(): Promise<LinkedInSource[]>;
+    /** Pull prospects from a source, normalized + capped. */
+    fetchProspects(options?: FetchProspectsOptions): Promise<LinkedInProspect[]>;
+}
+export declare const HEYREACH_BASE = "https://api.heyreach.io/api/public";
+export type HeyReachProviderOptions = {
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+    baseUrl?: string;
+    /** Lead-list id used when fetchProspects is called without an explicit sourceId. */
+    defaultListId?: string;
+    /** Page size for paginated reads (≤ server max). Lower in tests. */
+    pageSize?: number;
+};
+export declare function createHeyReachProvider(options: HeyReachProviderOptions): LinkedInProvider;
+/** Map a HeyReach lead (nested `profile` or flat) into the normalized shape. */
+export declare function normalizeHeyReachLead(raw: any): LinkedInProspect;
+export declare const FAKE_LINKEDIN_PROSPECTS: LinkedInProspect[];
+export type FakeLinkedInOptions = {
+    prospects?: LinkedInProspect[];
+    sources?: LinkedInSource[];
+    connection?: ConnectionStatus;
+};
+export declare function createFakeLinkedInProvider(opts?: FakeLinkedInOptions): LinkedInProvider;

package/dist/connectors/linkedin.js

@@ -0,0 +1,199 @@
+/**
+ * LinkedIn connector — Phase 1 discovery (read-only).
+ *
+ * A provider-agnostic surface for pulling prospects out of LinkedIn via a
+ * rented execution layer (default: HeyReach; Unipile is a drop-in alternative).
+ * Deliberately decoupled from the acquire spine — the `Icp`→filter and
+ * `LinkedInProspect`→`Prospect` bridges live in the `enrich acquire --source
+ * linkedin` wiring, not here — so this layer can land and be tested on its own.
+ *
+ * Phase 2 (future) extends `LinkedInProvider` with send actions
+ * (connect/message) routed through the plan/apply gate. Spec:
+ * docs/linkedin-connector-spec.md. Nothing here ever writes or sends.
+ */
+// ── HeyReach adapter ────────────────────────────────────────────────────────
+// Base + auth verified 2026-06-20: POST endpoints, `X-API-KEY` header, 300
+// req/min (429). Confirmed live: /auth/CheckApiKey, /list/GetAll. The
+// leads-from-list path has a documented gap in HeyReach's public docs and is
+// marked to reconcile at live validation (step 3, needs a real key).
+export const HEYREACH_BASE = "https://api.heyreach.io/api/public";
+const HEYREACH_MAX_PAGE = 100;
+export function createHeyReachProvider(options) {
+    const apiKey = options.apiKey;
+    if (!apiKey) {
+        throw new Error("HeyReach API key is required (`login heyreach` or HEYREACH_API_KEY).");
+    }
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const baseUrl = (options.baseUrl ?? HEYREACH_BASE).replace(/\/$/, "");
+    const pageSize = Math.max(1, Math.min(options.pageSize ?? HEYREACH_MAX_PAGE, HEYREACH_MAX_PAGE));
+    async function call(path, method, body) {
+        let response;
+        try {
+            response = await fetchImpl(`${baseUrl}${path}`, {
+                method,
+                // Secret travels in the header, never the URL (no leak via logs/history).
+                headers: {
+                    "X-API-KEY": apiKey,
+                    ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+                },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch {
+            throw new Error(`Cannot reach HeyReach at ${baseUrl}${path}. Check network access.`);
+        }
+        if (response.status === 429) {
+            const retry = response.headers.get("Retry-After");
+            throw new Error(`HeyReach rate limit (429)${retry ? `; retry after ${retry}s` : ""}. The cap is 300 requests/min.`);
+        }
+        if (!response.ok) {
+            await response.text().catch(() => undefined);
+            throw new Error(`HeyReach API error ${response.status} on ${path}. Check the API key and request.`);
+        }
+        if (response.status === 204)
+            return undefined;
+        return response.json().catch(() => undefined);
+    }
+    return {
+        name: "heyreach",
+        async checkConnection() {
+            try {
+                await call("/auth/CheckApiKey", "GET");
+                return { ok: true, detail: "HeyReach API key valid." };
+            }
+            catch (error) {
+                return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+            }
+        },
+        async listSources() {
+            const data = await call("/list/GetAll", "POST", { offset: 0, limit: HEYREACH_MAX_PAGE });
+            return toArray(data).map((item) => ({
+                id: String(item?.id ?? item?.listId ?? ""),
+                name: String(item?.name ?? item?.title ?? "(unnamed list)"),
+                count: typeof item?.totalItemsCount === "number"
+                    ? item.totalItemsCount
+                    : typeof item?.count === "number"
+                        ? item.count
+                        : undefined,
+            }));
+        },
+        async fetchProspects(opts = {}) {
+            const listId = opts.sourceId ?? options.defaultListId;
+            if (!listId) {
+                throw new Error("HeyReach fetchProspects needs a sourceId (lead-list id) or a configured defaultListId — list them with listSources().");
+            }
+            const max = opts.max ?? Number.POSITIVE_INFINITY;
+            const out = [];
+            let offset = 0;
+            while (out.length < max) {
+                const data = await call("/list/GetLeadsFromList", "POST", { listId, offset, limit: pageSize });
+                const items = toArray(data);
+                if (items.length === 0)
+                    break;
+                for (const item of items) {
+                    out.push(normalizeHeyReachLead(item));
+                    if (out.length >= max)
+                        break;
+                }
+                if (items.length < pageSize)
+                    break;
+                offset += items.length;
+            }
+            return out;
+        },
+    };
+}
+/** First value that is a non-empty string, else undefined (treats "" as absent). */
+function firstNonEmpty(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim() !== "")
+            return value;
+    }
+    return undefined;
+}
+/** HeyReach wraps list payloads as `{ items: [...] }` on some routes, bare arrays on others. */
+function toArray(data) {
+    if (Array.isArray(data))
+        return data;
+    if (Array.isArray(data?.items))
+        return data.items;
+    return [];
+}
+/** Map a HeyReach lead (nested `profile` or flat) into the normalized shape. */
+export function normalizeHeyReachLead(raw) {
+    const p = (raw && typeof raw === "object" && raw.profile) || raw || {};
+    const first = p.firstName ?? raw?.firstName ?? "";
+    const last = p.lastName ?? raw?.lastName ?? "";
+    const full = (p.fullName ?? raw?.fullName ?? `${first} ${last}`.trim()) || undefined;
+    return {
+        firstName: String(first ?? ""),
+        lastName: String(last ?? ""),
+        fullName: full,
+        headline: p.headline ?? raw?.headline ?? undefined,
+        jobTitle: p.position ?? p.jobTitle ?? raw?.position ?? undefined,
+        company: p.companyName ?? p.company ?? raw?.companyName ?? undefined,
+        profileUrl: String(p.profileUrl ?? p.linkedInUrl ?? raw?.profileUrl ?? raw?.linkedin_url ?? ""),
+        location: p.location ?? raw?.location ?? undefined,
+        // HeyReach exposes the raw `emailAddress` plus its own enrichment outputs
+        // (`enrichedEmailAddress`, `customEmailAddress`) — verified against the live
+        // /list/GetLeadsFromList schema 2026-06-20. Unresolved emails come back as
+        // "", so pick the first NON-EMPTY value (?? would keep the empty string).
+        email: firstNonEmpty(p.emailAddress, p.enrichedEmailAddress, p.customEmailAddress, p.email, raw?.emailAddress),
+        emailStatus: p.emailStatus ?? raw?.emailStatus ?? undefined,
+        raw,
+    };
+}
+// ── Fake provider (tests / dry-run with no key, no network) ─────────────────
+export const FAKE_LINKEDIN_PROSPECTS = [
+    {
+        firstName: "Dana",
+        lastName: "Okafor",
+        fullName: "Dana Okafor",
+        headline: "VP RevOps",
+        jobTitle: "VP Revenue Operations",
+        company: "Northwind Logistics",
+        profileUrl: "https://www.linkedin.com/in/dana-okafor",
+        location: "Chicago, IL",
+        email: "dana@northwind.example",
+        emailStatus: "verified",
+    },
+    {
+        firstName: "Priya",
+        lastName: "Raman",
+        fullName: "Priya Raman",
+        headline: "Head of Sales Ops",
+        jobTitle: "Head of Sales Operations",
+        company: "Cobalt Health",
+        profileUrl: "https://www.linkedin.com/in/priya-raman",
+        location: "Austin, TX",
+    },
+    {
+        firstName: "Marco",
+        lastName: "Bianchi",
+        fullName: "Marco Bianchi",
+        headline: "RevOps Manager",
+        jobTitle: "Revenue Operations Manager",
+        company: "Ferro Systems",
+        profileUrl: "https://www.linkedin.com/in/marco-bianchi",
+        location: "Remote",
+        email: "marco@ferro.example",
+        emailStatus: "guessed",
+    },
+];
+export function createFakeLinkedInProvider(opts = {}) {
+    const prospects = opts.prospects ?? FAKE_LINKEDIN_PROSPECTS;
+    const sources = opts.sources ?? [{ id: "list_demo", name: "Demo ICP list", count: prospects.length }];
+    return {
+        name: "fake",
+        async checkConnection() {
+            return opts.connection ?? { ok: true, detail: "fake LinkedIn provider" };
+        },
+        async listSources() {
+            return sources.map((s) => ({ ...s }));
+        },
+        async fetchProspects(options = {}) {
+            const capped = options.max != null ? prospects.slice(0, options.max) : prospects;
+            return capped.map((p) => ({ ...p }));
+        },
+    };
+}

package/dist/connectors/prospectSources.d.ts

@@ -0,0 +1,91 @@
+/**
+ * API prospect sources for `enrich acquire` — net-new lead discovery + email
+ * resolution, behind one normalized shape the acquire builder consumes.
+ *
+ * Two confirmed providers (others slot in the same way):
+ *  - Explorium  — net-new discovery (POST /v1/prospects). Returns names, titles,
+ *    company + website, LinkedIn; the email it returns is HASHED, so it is a
+ *    discovery source, not an email source.
+ *  - pipe0      — work-email resolution (POST /v1/pipes/run/sync with the
+ *    `person:workemail:waterfall@1` block). Turns {name, company_domain} into a
+ *    real work email. This is the email leg for Explorium-discovered people.
+ *
+ * Zero runtime deps: global fetch only, injectable for tests. Keys arrive via
+ * env/credential store, never argv.
+ */
+import type { CanonicalGtmSnapshot } from "../types.ts";
+export type Prospect = {
+    firstName?: string;
+    lastName?: string;
+    fullName?: string;
+    jobTitle?: string;
+    /** normalized seniority, e.g. "cxo","vp","director" (Explorium job_level_main) */
+    jobLevel?: string;
+    /** normalized department, e.g. "sales" (Explorium job_department_main) */
+    jobDepartment?: string;
+    companyName?: string;
+    /** bare domain, e.g. "microsoft.com" — feeds pipe0's company_domain */
+    companyDomain?: string;
+    linkedin?: string;
+    /** real work email once resolved (pipe0); never the hashed value */
+    email?: string;
+    /** ICP fit score 0..1, set by the acquire scorer */
+    fitScore?: number;
+    /** provider-native id for traceability */
+    sourceId?: string;
+};
+type FetchImpl = typeof fetch;
+export type ExploriumFilters = Record<string, {
+    values?: string[];
+    value?: boolean;
+}>;
+export declare function fetchExploriumProspects(opts: {
+    apiKey: string;
+    filters: ExploriumFilters;
+    size?: number;
+    apiBaseUrl?: string;
+    fetchImpl?: FetchImpl;
+}): Promise<Prospect[]>;
+export declare function fetchPipe0CrustdataProspects(opts: {
+    apiKey: string;
+    filters: Record<string, unknown>;
+    limit?: number;
+    apiBaseUrl?: string;
+    fetchImpl?: FetchImpl;
+}): Promise<Prospect[]>;
+/**
+ * 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 declare function pipe0ResolveWorkEmails(opts: {
+    apiKey: string;
+    prospects: Prospect[];
+    apiBaseUrl?: string;
+    fetchImpl?: FetchImpl;
+    /** Rows per pipe0 call. Small chunks are resilient to the waterfall's
+     *  batch rate-limit (a throttled chunk returns work_email status "failed"
+     *  for every row, so one big batch is all-or-nothing). Default 3. */
+    chunkSize?: number;
+}): Promise<Prospect[]>;
+/**
+ * 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 declare function prospectIdentityKeys(p: Prospect): string[];
+/** Identity keys for every contact already in the CRM snapshot (email + name|domain). */
+export declare function crmContactKeys(snapshot: CanonicalGtmSnapshot): Set<string>;
+/**
+ * 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 declare function partitionFreshProspects(prospects: Prospect[], crmKeys: Set<string>, seen: Set<string>): {
+    fresh: Prospect[];
+    skippedCrm: number;
+    skippedSeen: number;
+};
+export {};