fullstackgtm 0.33.0 → 0.37.0

package/src/icp.ts

@@ -0,0 +1,313 @@
+/**
+ * ICP — the Ideal Customer Profile that makes `enrich acquire` targeted instead
+ * of random. One structured artifact drives two things:
+ *   1. discovery filters — translated per provider (Explorium, pipe0/Crustdata)
+ *      so the pull only returns ICP-shaped companies + people, and
+ *   2. fit scoring — every discovered prospect is scored against the persona so
+ *      only above-threshold leads become create_record ops.
+ *
+ * Develop one via interview: an agent (Claude Code / Codex) reads INTERVIEW_SPEC,
+ * asks the questions with its AskUserQuestion tool, and writes the answers into
+ * an Icp (CLI: `icp interview` emits the spec, `icp show` renders the result).
+ *
+ * Zero runtime deps; pure functions (translation + scoring take plain data).
+ */
+
+export type Icp = {
+  name: string;
+  firmographics: {
+    /** human industry labels, e.g. ["software","saas"] — used for keyword/industry filters */
+    industries?: string[];
+    /** Explorium naics_category codes, e.g. ["5112"] (software publishers) */
+    naics?: string[];
+    /** provider-agnostic employee bands: "1-10","11-50","51-200","201-500","501-1000","1001-5000","5001-10000","10001+" */
+    employeeBands?: string[];
+    /** ISO country codes, lowercased, e.g. ["us"] */
+    geos?: string[];
+  };
+  persona: {
+    /** seniority: "cxo","vp","director","manager","owner","senior" */
+    jobLevels?: string[];
+    /** "sales","marketing","operations","finance" */
+    departments?: string[];
+    /** the title phrases that DEFINE the buyer — also the scoring signal */
+    titleKeywords?: string[];
+  };
+  signals?: { intentTopics?: string[] };
+  scoring?: {
+    /** minimum fit (0..1) for a prospect to become a create_record op. Default 0.5. */
+    threshold?: number;
+  };
+};
+
+export const DEFAULT_FIT_THRESHOLD = 0.5;
+
+const COUNTRY_NAMES: Record<string, string> = {
+  us: "United States",
+  ca: "Canada",
+  gb: "United Kingdom",
+  uk: "United Kingdom",
+};
+
+export function parseIcp(raw: string): Icp {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`icp: not valid JSON (${error instanceof Error ? error.message : String(error)})`);
+  }
+  if (!parsed || typeof parsed !== "object") throw new Error("icp: expected a JSON object");
+  const icp = parsed as Icp;
+  if (!icp.name || typeof icp.name !== "string") throw new Error('icp: missing "name"');
+  if (!icp.persona || (!icp.persona.titleKeywords?.length && !icp.persona.jobLevels?.length)) {
+    throw new Error('icp: "persona" needs at least titleKeywords or jobLevels (without them, scoring cannot rank fit)');
+  }
+  return icp;
+}
+
+// ---------------------------------------------------------------------------
+// Discovery-filter translation
+
+/** Explorium /v1/prospects filters from the ICP. */
+export function icpToExploriumFilters(icp: Icp): Record<string, { values?: string[]; value?: boolean }> {
+  const f: Record<string, { values?: string[]; value?: boolean }> = { has_email: { value: true } };
+  if (icp.persona.jobLevels?.length) f.job_level = { values: icp.persona.jobLevels };
+  if (icp.persona.departments?.length) f.job_department = { values: icp.persona.departments };
+  if (icp.firmographics.employeeBands?.length) f.company_size = { values: icp.firmographics.employeeBands };
+  if (icp.firmographics.geos?.length) f.company_country_code = { values: icp.firmographics.geos };
+  if (icp.firmographics.naics?.length) f.naics_category = { values: icp.firmographics.naics };
+  return f;
+}
+
+/**
+ * Crustdata / LinkedIn seniority vocab. ICP job levels are normalized lowercase;
+ * Crustdata expects these exact capitalized strings (verified: "CXO",
+ * "Vice President", "Director" appear in Crustdata's docs/examples).
+ */
+const CRUSTDATA_SENIORITY: Record<string, string> = {
+  cxo: "CXO",
+  "c-suite": "CXO",
+  c_suite: "CXO",
+  founder: "Owner",
+  owner: "Owner",
+  partner: "Partner",
+  vp: "Vice President",
+  "vice president": "Vice President",
+  head: "Director",
+  director: "Director",
+  manager: "Manager",
+  senior: "Senior",
+  entry: "Entry",
+};
+
+/**
+ * ICP industry keyword → LinkedIn industry names Crustdata filters on. Includes
+ * the current LinkedIn-v2 names; for software we send the cluster (dev + IT
+ * services + internet) so an OR match isn't overly narrow.
+ */
+const CRUSTDATA_INDUSTRY: Record<string, string[]> = {
+  software: ["Software Development", "Information Technology and Services", "Internet"],
+  saas: ["Software Development", "Information Technology and Services"],
+  "information technology & services": ["Information Technology and Services"],
+  "information technology and services": ["Information Technology and Services"],
+  internet: ["Internet"],
+  fintech: ["Financial Services"],
+  "financial services": ["Financial Services"],
+};
+
+/**
+ * pipe0 Crustdata people-search config.filters from the ICP. `current_job_titles`
+ * matches real LinkedIn title strings (case-sensitive), so keywords are Title
+ * Cased. Seniority + industry are mapped to Crustdata's controlled vocab via the
+ * tables above. NOTE: the exact pipe0→Crustdata value set could not be re-run
+ * live (pipe0 credits were exhausted) — validate when credits refill; fit
+ * scoring is the safety net for persona precision regardless.
+ */
+export function icpToCrustdataFilters(icp: Icp): Record<string, unknown> {
+  const f: Record<string, unknown> = {};
+  if (icp.persona.titleKeywords?.length) f.current_job_titles = icp.persona.titleKeywords.map(titleCase);
+  if (icp.firmographics.geos?.length) {
+    f.locations = icp.firmographics.geos.map((g) => COUNTRY_NAMES[g.toLowerCase()] ?? g);
+  }
+  if (icp.persona.jobLevels?.length) {
+    const include = [...new Set(icp.persona.jobLevels.map((l) => CRUSTDATA_SENIORITY[l.toLowerCase()]).filter(Boolean))];
+    if (include.length) f.current_seniority_levels = { include, exclude: [] };
+  }
+  if (icp.firmographics.industries?.length) {
+    const inds = [
+      ...new Set(icp.firmographics.industries.flatMap((i) => CRUSTDATA_INDUSTRY[i.toLowerCase()] ?? [titleCase(i)])),
+    ];
+    if (inds.length) f.current_employers_linkedin_industries = inds;
+  }
+  return f;
+}
+
+const ACRONYMS = new Set(["cro", "coo", "ceo", "cfo", "vp", "crm", "gtm", "saas"]);
+function titleCase(value: string): string {
+  return value
+    .split(/\s+/)
+    .map((w) => (ACRONYMS.has(w.toLowerCase()) ? w.toUpperCase() : w.charAt(0).toUpperCase() + w.slice(1)))
+    .join(" ");
+}
+
+// ---------------------------------------------------------------------------
+// Fit scoring (persona precision; firmographics are enforced by the filter)
+
+export type IcpFit = { score: number; reasons: string[] };
+
+/**
+ * Score a prospect's PERSONA fit 0..1. Title-keyword match is the strongest
+ * signal (it's what defines the buyer); job level and department add to it.
+ * Firmographics aren't re-scored here — discovery already filtered on them.
+ */
+export function scoreProspectAgainstIcp(
+  prospect: { jobTitle?: string; jobLevel?: string; jobDepartment?: string },
+  icp: Icp,
+): IcpFit {
+  const reasons: string[] = [];
+  const title = (prospect.jobTitle ?? "").toLowerCase();
+  const keywords = (icp.persona.titleKeywords ?? []).map((k) => k.toLowerCase());
+  const levels = (icp.persona.jobLevels ?? []).map((l) => l.toLowerCase());
+  const depts = (icp.persona.departments ?? []).map((d) => d.toLowerCase());
+
+  let score = 0;
+  let weightSum = 0;
+
+  if (keywords.length) {
+    weightSum += 0.6;
+    const hit = keywords.find((k) => title.includes(k));
+    if (hit) {
+      score += 0.6;
+      reasons.push(`title matches ICP keyword "${hit}"`);
+    }
+  }
+  if (levels.length) {
+    weightSum += 0.25;
+    const level = (prospect.jobLevel ?? "").toLowerCase();
+    if (level && levels.some((l) => level.includes(l))) {
+      score += 0.25;
+      reasons.push(`seniority "${prospect.jobLevel}" in ICP levels`);
+    }
+  }
+  if (depts.length) {
+    weightSum += 0.15;
+    const dept = (prospect.jobDepartment ?? "").toLowerCase();
+    if (dept && depts.some((d) => dept.includes(d))) {
+      score += 0.15;
+      reasons.push(`department "${prospect.jobDepartment}" in ICP`);
+    }
+  }
+  const normalized = weightSum > 0 ? score / weightSum : 0;
+  if (reasons.length === 0) reasons.push("no persona signal matched the ICP");
+  return { score: Number(normalized.toFixed(3)), reasons };
+}
+
+export function fitThreshold(icp: Icp): number {
+  return icp.scoring?.threshold ?? DEFAULT_FIT_THRESHOLD;
+}
+
+// ---------------------------------------------------------------------------
+// Interview spec — an agent drives this with AskUserQuestion, then writes an Icp
+
+export type IcpInterviewQuestion = {
+  id: keyof FlatIcpAnswers;
+  header: string;
+  question: string;
+  multiSelect: boolean;
+  options: { label: string; value: string | string[]; description: string }[];
+};
+
+/** Flattened answer keys the interview collects (assembled into an Icp). */
+export type FlatIcpAnswers = {
+  industries: string[];
+  employeeBands: string[];
+  jobLevels: string[];
+  departments: string[];
+  titleKeywords: string[];
+  geos: string[];
+};
+
+export const INTERVIEW_SPEC: IcpInterviewQuestion[] = [
+  {
+    id: "industries",
+    header: "Target market",
+    question: "What company profile are you targeting? (Drives firmographic discovery filters.)",
+    multiSelect: true,
+    options: [
+      { label: "B2B SaaS / software", value: ["software", "saas"], description: "Software & internet — classic messy-CRM, RevOps-equipped buyer." },
+      { label: "Broader tech-enabled B2B", value: ["software", "information technology & services", "financial services"], description: "Any B2B running a real sales motion on a CRM." },
+      { label: "Any B2B with a CRM", value: [], description: "Vertical-agnostic — qualify on persona, not industry." },
+    ],
+  },
+  {
+    id: "employeeBands",
+    header: "Company size",
+    question: "Company size (employee bands) that fit?",
+    multiSelect: true,
+    options: [
+      { label: "Seed–Series A (1–50)", value: ["1-10", "11-50"], description: "Early; often no dedicated RevOps yet." },
+      { label: "Series B–C (51–500)", value: ["51-200", "201-500"], description: "Sweet spot: messy CRM, RevOps exists, budget exists." },
+      { label: "Growth (501–2000)", value: ["501-1000", "1001-5000"], description: "Established RevOps, many CRM writers." },
+      { label: "Enterprise (2000+)", value: ["1001-5000", "5001-10000", "10001+"], description: "Up-market; longer cycles." },
+    ],
+  },
+  {
+    id: "titleKeywords",
+    header: "Buyer persona",
+    question: "Which buyer persona(s) should discovery target and scoring reward?",
+    multiSelect: true,
+    options: [
+      { label: "RevOps leadership", value: ["revenue operations", "revops", "head of revenue operations"], description: "VP/Head/Dir Revenue Operations." },
+      { label: "Sales/Marketing Ops", value: ["sales operations", "gtm operations", "marketing operations", "revenue ops"], description: "Hands-on the CRM daily." },
+      { label: "Exec buyers", value: ["chief revenue officer", "cro", "chief operating officer", "vp of sales"], description: "Economic sign-off." },
+      { label: "CRM/SF admins", value: ["salesforce admin", "hubspot admin", "crm manager", "revops analyst"], description: "Feel the pain, champion the fix." },
+    ],
+  },
+  {
+    id: "geos",
+    header: "Geography",
+    question: "Geography?",
+    multiSelect: true,
+    options: [
+      { label: "United States", value: ["us"], description: "US-only (best data coverage)." },
+      { label: "US + Canada", value: ["us", "ca"], description: "North America." },
+      { label: "US + UK/EU", value: ["us", "gb"], description: "English-speaking + Western Europe (mind GDPR)." },
+      { label: "Global", value: [], description: "No geo filter." },
+    ],
+  },
+];
+
+/** Assemble an Icp from flattened interview answers. */
+export function icpFromAnswers(name: string, answers: FlatIcpAnswers): Icp {
+  const levelsFromTitles = inferLevels(answers.titleKeywords);
+  return {
+    name,
+    firmographics: {
+      industries: dedupe(answers.industries),
+      naics: answers.industries.some((i) => /software|saas/i.test(i)) ? ["5112"] : undefined,
+      employeeBands: dedupe(answers.employeeBands),
+      geos: dedupe(answers.geos),
+    },
+    persona: {
+      jobLevels: answers.jobLevels?.length ? dedupe(answers.jobLevels) : levelsFromTitles,
+      departments: answers.departments?.length ? dedupe(answers.departments) : ["sales", "marketing", "operations"],
+      titleKeywords: dedupe(answers.titleKeywords),
+    },
+    scoring: { threshold: DEFAULT_FIT_THRESHOLD },
+  };
+}
+
+function inferLevels(titles: string[]): string[] {
+  const levels = new Set<string>();
+  for (const t of titles.map((x) => x.toLowerCase())) {
+    if (/chief|^c[a-z]o$|cro|coo/.test(t)) levels.add("cxo");
+    if (/vp|vice president|head of/.test(t)) levels.add("vp");
+    if (/director/.test(t)) levels.add("director");
+    if (/manager|admin|analyst|operations/.test(t)) levels.add("manager");
+  }
+  return levels.size ? [...levels] : ["cxo", "vp", "director", "manager"];
+}
+
+function dedupe(values: string[] | undefined): string[] {
+  return [...new Set((values ?? []).filter(Boolean))];
+}

package/src/index.ts

@@ -131,6 +131,14 @@ export {
   type AuditLogVerification,
 } from "./auditLog.ts";
 export { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
+export {
+  computeHealth,
+  summarizeHealth,
+  healthToMarkdown,
+  type HealthEntry,
+  type HealthRollup,
+  type HealthRuleDelta,
+} from "./health.ts";
 export { auditReportToHtml, auditReportToMarkdown, type ReportOptions } from "./report.ts";
 export {
   HUBSPOT_DEFAULT_FIELD_MAPPINGS,
@@ -301,9 +309,12 @@ export {
   findCategoryPageInSitemap,
   findCategoryPage,
   fetchLogoDataUri,
+  discoverCompetitors,
   type FetchText,
   type FetchBytes,
   type ResolveUrl,
+  type DiscoveredVendor,
+  type DiscoverCompetitorsOptions,
 } from "./marketSourcing.ts";
 export {
   computeMissedFirings,

package/src/mappings.ts

@@ -22,6 +22,9 @@ export const HUBSPOT_DEFAULT_FIELD_MAPPINGS: Record<
     email: "email",
     phone: "phone",
     title: "jobtitle",
+    // HubSpot-standard "LinkedIn URL"; safe to request everywhere (HubSpot
+    // ignores unknown properties rather than erroring). Powers strong dedup.
+    linkedin: "hs_linkedin_url",
     ownerId: "hubspot_owner_id",
   },
   deals: {

package/src/marketSourcing.ts

@@ -17,6 +17,7 @@
  *    headless browser, so the default fetch is sufficient even in the hosted layer.
  */
 import { assertPublicUrl } from "./market.ts";
+import { DEFAULT_MODELS, forcedToolCall, type LlmCallOptions } from "./llm.ts";
 
 const USER_AGENT = "fullstackgtm-market/0 (+https://github.com/fullstackgtm/core)";
 const FETCH_TIMEOUT_MS = 15_000;
@@ -403,3 +404,106 @@ export async function fetchLogoDataUri(
   }
   return null;
 }
+
+// ── Competitor discovery ─────────────────────────────────────────────────────
+
+/** A vendor proposed by `discoverCompetitors`. */
+export type DiscoveredVendor = {
+  name: string;
+  /** Canonical homepage. */
+  url: string;
+  /** The page most specific to the category — the product page for multi-product
+   *  companies, else the homepage. Use as the capture seed. */
+  productUrl: string;
+};
+
+export type DiscoverCompetitorsOptions = {
+  llm: LlmCallOptions;
+  /** The user's own company: competitors are listed for it and it's excluded. */
+  anchorUrl?: string;
+  /** Vendor hosts already in the set, to exclude from results. */
+  exclude?: string[];
+};
+
+const DISCOVERY_SCHEMA = {
+  type: "object",
+  required: ["competitors"],
+  properties: {
+    competitors: {
+      type: "array",
+      description: "Real vendors competing in this category today, each with its canonical https homepage URL.",
+      items: {
+        type: "object",
+        required: ["name", "url"],
+        properties: {
+          name: { type: "string" },
+          url: { type: "string", description: "Canonical homepage, https://domain, no tracking path." },
+          productUrl: {
+            type: "string",
+            description:
+              "URL of the page on THIS vendor's site most specific to the category. For a multi-product company (e.g. SAP, Oracle) this is the product/solution page for this category, NOT the corporate homepage. For a focused single-product vendor, repeat the homepage.",
+          },
+        },
+      },
+    },
+  },
+};
+
+/**
+ * Propose the real vendor set for a category via the LLM — so a cold-start map
+ * needs only a category, not a hand-built vendor list. Returns canonical homepages
+ * plus a category-specific `productUrl` per vendor; excludes the anchor + any
+ * supplied hosts, de-dupes by registrable domain, and instructs the model to skip
+ * acquired/defunct brands. BYOK via the package's `forcedToolCall`.
+ */
+export async function discoverCompetitors(
+  category: string,
+  options: DiscoverCompetitorsOptions,
+): Promise<DiscoveredVendor[]> {
+  const model = options.llm.model ?? DEFAULT_MODELS[options.llm.provider];
+  const anchorHost = options.anchorUrl ? hostOf(options.anchorUrl) : null;
+  const anchorNote = anchorHost
+    ? `The user's own company is ${anchorHost} — list its direct competitors and do NOT include ${anchorHost} itself.`
+    : "";
+  const prompt = `List the most significant vendors competing in the category "${category}" today.
+${anchorNote}
+Rules:
+- Real companies only, each with its canonical https homepage URL (domain root, no tracking path).
+- 7-9 vendors: a mix of established leaders and notable challengers.
+- EXCLUDE vendors that have been acquired and folded into another brand, or are defunct — i.e. anything whose own site now redirects to a different company. (Name the current independent players instead.)
+- For each, also give productUrl: the page most specific to "${category}". For a big multi-product company, that's its product/solution page for THIS category, not the corporate homepage.
+- No duplicates.`;
+  const result = (await forcedToolCall(prompt, "discover_competitors", DISCOVERY_SCHEMA, model, options.llm)) as {
+    competitors?: Array<{ name?: string; url?: string; productUrl?: string }>;
+  };
+
+  const excluded = new Set((options.exclude ?? []).map(hostOf).filter((h): h is string => Boolean(h)));
+  if (anchorHost) excluded.add(anchorHost);
+  const seenDomain = new Set<string>();
+  const out: DiscoveredVendor[] = [];
+  for (const c of result?.competitors ?? []) {
+    let u: URL;
+    try {
+      u = new URL(String(c.url));
+    } catch {
+      continue;
+    }
+    if (u.protocol !== "http:" && u.protocol !== "https:") continue;
+    const host = u.hostname.replace(/^www\./, "");
+    if (excluded.has(host)) continue;
+    const dom = registrableDomain(host);
+    if (seenDomain.has(dom)) continue;
+    seenDomain.add(dom);
+    let productUrl = u.toString();
+    if (c.productUrl) {
+      try {
+        const p = new URL(String(c.productUrl));
+        if (p.protocol === "http:" || p.protocol === "https:") productUrl = p.toString();
+      } catch {
+        /* keep homepage */
+      }
+    }
+    out.push({ name: c.name || host, url: u.toString(), productUrl });
+  }
+  return out;
+}

package/src/types.ts

@@ -43,11 +43,33 @@ export type PatchOperationType =
   | "link_record"
   | "archive_record"
   | "create_task"
+  // Create a NET-NEW record (a sourced lead). beforeValue is null (nothing
+  // existed); afterValue is a CreateRecordPayload. The connector re-resolves
+  // on matchKey at apply time (search is the source of truth; the plan-time
+  // snapshot can be stale) and creates only on a confirmed miss, so apply is
+  // resolve-first and never double-creates a record a concurrent writer added.
+  // Emitted only by `enrich acquire`, and metered against the acquire budget.
+  | "create_record"
   // Merge a duplicate group into a survivor. beforeValue is the group's
   // record ids; afterValue is the survivor id (requires_human_survivor_selection
   // until a human picks). IRREVERSIBLE on every provider that supports it.
   | "merge_records";
 
+/**
+ * The afterValue of a `create_record` operation. The connector re-resolves on
+ * `matchKey`/`matchValue` at apply time and creates only on a confirmed miss.
+ * `estCostUsd` is the acquire meter's per-record charge, recorded against the
+ * budget on a successful create.
+ */
+export type CreateRecordPayload = {
+  properties: Record<string, string>;
+  matchKey: string;
+  matchValue: string;
+  source: string;
+  estCostUsd?: number;
+  associateCompanyName?: string;
+};
+
 export type AuditFindingSeverity = "info" | "warning" | "critical";
 
 /**
@@ -186,6 +208,8 @@ export type CanonicalContact = {
   email?: string;
   phone?: string;
   title?: string;
+  /** LinkedIn profile URL — the strongest cross-system identity key for dedup. */
+  linkedin?: string;
   ownerId?: string;
   lastActivityAt?: string;
   lastSyncAt?: string;