fullstackgtm 0.34.0 → 0.38.0

package/src/connectors/hubspot.ts

@@ -13,6 +13,7 @@ import type {
   RecordProvenance,
   CanonicalGtmSnapshot,
   CanonicalUser,
+  CreateRecordPayload,
   GtmConnector,
   GtmObjectType,
   PatchOperation,
@@ -59,6 +60,10 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
   // 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<string, string>();
+  // 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<string, string>();
 
   async function request(path: string, init: RequestInit = {}): Promise<any> {
     const token = await options.getAccessToken();
@@ -220,6 +225,7 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
           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"),
           ),
@@ -513,6 +519,143 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     return ((data?.results ?? []) as Array<{ id: string }>).map((row) => String(row.id));
   }
 
+  /** Exact-value contact lookup (by any searchable property) for resolve-first creates. */
+  async function searchContactsBy(property: string, value: string): Promise<string[]> {
+    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 ?? []) as Array<{ id: string }>).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: string, opId: string): Promise<string | null> {
+    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: PatchOperation): Promise<PatchOperationResult> {
+    const payload = operation.afterValue as CreateRecordPayload | undefined;
+    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: Record<string, string> = { ...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: PatchOperation): Promise<PatchOperationResult> {
     const associationTypeId = TASK_ASSOCIATION_TYPE_IDS[operation.objectType];
     if (associationTypeId === undefined) {
@@ -707,6 +850,8 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
           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/src/connectors/linkedin.ts

@@ -0,0 +1,272 @@
+/**
+ * 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[]>;
+}
+
+// ── 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 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 function createHeyReachProvider(options: HeyReachProviderOptions): LinkedInProvider {
+  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: string, method: "GET" | "POST", body?: unknown): Promise<any> {
+    let response: 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: any) => ({
+        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: LinkedInProspect[] = [];
+      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: unknown[]): string | undefined {
+  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: any): any[] {
+  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: any): LinkedInProspect {
+  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: LinkedInProspect[] = [
+  {
+    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 type FakeLinkedInOptions = {
+  prospects?: LinkedInProspect[];
+  sources?: LinkedInSource[];
+  connection?: ConnectionStatus;
+};
+
+export function createFakeLinkedInProvider(opts: FakeLinkedInOptions = {}): LinkedInProvider {
+  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 }));
+    },
+  };
+}