@dench.com/cli 2.7.5 → 2.7.6-staging.1

package/lib/exa-companies.ts

@@ -0,0 +1,389 @@
+/**
+ * Exa Company Search — entity parsing, Apollo-shape projection, and matching.
+ *
+ * The company twin of `exa-people.ts`. Exa's Company Search (`POST /search`
+ * with `category: "company"`) covers 50M+ company pages and returns structured
+ * firmographics on `results[].entities[]` as
+ * `{ id, type: "company", version, properties }`.
+ *
+ * Same two jobs as the people mapper: project into the Apollo-shaped envelope
+ * the existing extraction machinery already speaks, and refuse to hand back a
+ * company whose identity is not corroborated (Exa is a search, so it always
+ * returns *something*).
+ *
+ * Company matching is materially safer than person matching, because a company
+ * has a domain and a domain is an identity. When the caller knows the domain
+ * we compare hostnames and that is that; only the name-only path needs care.
+ *
+ * Field shapes are taken from live responses, not just the docs — real
+ * payloads carry an undocumented `research` key and frequently null out
+ * `webTraffic` and `financials.fundingLatestRound`, so everything is read
+ * defensively.
+ */
+
+import {
+  asArray,
+  asObject,
+  asString,
+  normalizeCompany,
+  withScheme,
+} from "./exa-people";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ExaCompanyHeadquarters = {
+  address?: string;
+  city?: string;
+  postalCode?: string;
+  country?: string;
+};
+
+export type ExaFundingRound = {
+  name?: string;
+  date?: string;
+  amount?: number;
+};
+
+export type ExaCompanyFinancials = {
+  revenueAnnual?: number;
+  fundingTotal?: number;
+  fundingLatestRound?: ExaFundingRound | null;
+};
+
+export type ExaWebTraffic = {
+  visitsMonthly?: number;
+  countryRank?: number;
+  avgDurationSeconds?: number;
+};
+
+export type ExaCompany = {
+  /** Stable Exa company entity id, when present. */
+  id?: string;
+  name?: string;
+  foundedYear?: number;
+  description?: string;
+  /** Estimated total headcount (`workforce.total`). */
+  headcount?: number;
+  headquarters?: ExaCompanyHeadquarters | null;
+  financials?: ExaCompanyFinancials | null;
+  webTraffic?: ExaWebTraffic | null;
+};
+
+export type ExaCompanyHit = {
+  /** Company URL from the enclosing search result. May be "" if absent. */
+  url: string;
+  title?: string;
+  highlights?: string[];
+  company: ExaCompany;
+};
+
+// ---------------------------------------------------------------------------
+// Defensive readers
+// ---------------------------------------------------------------------------
+
+function asFiniteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
+function asStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out = value.filter(
+    (item): item is string =>
+      typeof item === "string" && item.trim().length > 0,
+  );
+  return out.length > 0 ? out : undefined;
+}
+
+function readHeadquarters(value: unknown): ExaCompanyHeadquarters | null {
+  const raw = asObject(value);
+  if (!raw) return null;
+  const hq: ExaCompanyHeadquarters = {
+    address: asString(raw.address),
+    city: asString(raw.city),
+    postalCode: asString(raw.postalCode),
+    country: asString(raw.country),
+  };
+  return Object.values(hq).some((part) => part !== undefined) ? hq : null;
+}
+
+function readFundingRound(value: unknown): ExaFundingRound | null {
+  const raw = asObject(value);
+  if (!raw) return null;
+  const round: ExaFundingRound = {
+    name: asString(raw.name),
+    date: asString(raw.date),
+    amount: asFiniteNumber(raw.amount),
+  };
+  return Object.values(round).some((part) => part !== undefined) ? round : null;
+}
+
+function readFinancials(value: unknown): ExaCompanyFinancials | null {
+  const raw = asObject(value);
+  if (!raw) return null;
+  const financials: ExaCompanyFinancials = {
+    revenueAnnual: asFiniteNumber(raw.revenueAnnual),
+    fundingTotal: asFiniteNumber(raw.fundingTotal),
+    fundingLatestRound: readFundingRound(raw.fundingLatestRound),
+  };
+  const hasValue =
+    financials.revenueAnnual !== undefined ||
+    financials.fundingTotal !== undefined ||
+    financials.fundingLatestRound !== null;
+  return hasValue ? financials : null;
+}
+
+function readWebTraffic(value: unknown): ExaWebTraffic | null {
+  const raw = asObject(value);
+  if (!raw) return null;
+  const traffic: ExaWebTraffic = {
+    visitsMonthly: asFiniteNumber(raw.visitsMonthly),
+    countryRank: asFiniteNumber(raw.countryRank),
+    avgDurationSeconds: asFiniteNumber(raw.avgDurationSeconds),
+  };
+  return Object.values(traffic).some((part) => part !== undefined)
+    ? traffic
+    : null;
+}
+
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+
+/** Walk an Exa `/search` response and pull out every company entity. */
+export function parseExaCompanyResults(data: unknown): ExaCompanyHit[] {
+  const root = asObject(data);
+  if (!root) return [];
+  const hits: ExaCompanyHit[] = [];
+
+  for (const entry of asArray(root.results)) {
+    const result = asObject(entry);
+    if (!result) continue;
+    const url = asString(result.url) ?? asString(result.link) ?? "";
+    const title = asString(result.title);
+    const highlights = asStringArray(result.highlights);
+
+    for (const entityEntry of asArray(result.entities)) {
+      const entity = asObject(entityEntry);
+      if (!entity) continue;
+      if (asString(entity.type) !== "company") continue;
+      const properties = asObject(entity.properties);
+      if (!properties) continue;
+
+      hits.push({
+        url,
+        title,
+        highlights,
+        company: {
+          id: asString(entity.id),
+          name: asString(properties.name),
+          foundedYear: asFiniteNumber(properties.foundedYear),
+          description: asString(properties.description),
+          headcount: asFiniteNumber(asObject(properties.workforce)?.total),
+          headquarters: readHeadquarters(properties.headquarters),
+          financials: readFinancials(properties.financials),
+          webTraffic: readWebTraffic(properties.webTraffic),
+        },
+      });
+    }
+  }
+
+  return hits;
+}
+
+// ---------------------------------------------------------------------------
+// Domain helpers
+// ---------------------------------------------------------------------------
+
+/** Hostname without protocol, `www.`, path, query, or trailing dot. */
+export function normalizeDomain(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) return "";
+  let host = trimmed;
+  try {
+    host = new URL(withScheme(trimmed)).hostname;
+  } catch {
+    host = trimmed.split("/")[0].split("?")[0];
+  }
+  return host
+    .toLowerCase()
+    .replace(/^www\./, "")
+    .replace(/\.$/, "");
+}
+
+/**
+ * A domain is accepted as identity evidence only when hostnames are exact.
+ * Parent/subdomain matching is unsafe on shared hosting:
+ * `tenant.vercel.app` and `vercel.app` are not necessarily the same company.
+ */
+function domainsAgree(left: string, right: string): boolean {
+  const a = normalizeDomain(left);
+  const b = normalizeDomain(right);
+  if (!a || !b) return false;
+  return a === b;
+}
+
+/** Format a USD amount the way the CRM funding columns expect ("$11.3B"). */
+export function formatUsdCompact(amount: number | undefined): string | null {
+  if (amount === undefined || !Number.isFinite(amount)) return null;
+  const abs = Math.abs(amount);
+  const units: Array<[number, string]> = [
+    [1e12, "T"],
+    [1e9, "B"],
+    [1e6, "M"],
+    [1e3, "K"],
+  ];
+  for (const [size, suffix] of units) {
+    if (abs >= size) {
+      const scaled = amount / size;
+      // One decimal below 100 ("$11.3B"), none above ("$250M").
+      const digits = Math.abs(scaled) < 100 ? 1 : 0;
+      return `$${scaled.toFixed(digits).replace(/\.0$/, "")}${suffix}`;
+    }
+  }
+  return `$${Math.round(amount)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Apollo-shape projection
+// ---------------------------------------------------------------------------
+
+/**
+ * Project a company hit into the Apollo-shaped envelope the existing
+ * enrichment extractors understand.
+ *
+ * The keys mirror the `apolloPath` values already declared by
+ * COMPANY_ENRICHMENT_COLUMNS (`organization.name`, `organization.domain`,
+ * `organization.description`, `organization.headcount`, …) so Exa can back
+ * those columns without touching the extractor.
+ */
+export function toCompanyApolloEnvelope(
+  hit: ExaCompanyHit,
+): Record<string, unknown> {
+  const { company } = hit;
+  const hq = company.headquarters;
+  const financials = company.financials;
+  const domain = hit.url ? normalizeDomain(hit.url) : null;
+  const hqLocation =
+    [hq?.city, hq?.country].filter(Boolean).join(", ") || hq?.address || null;
+
+  const organization: Record<string, unknown> = {
+    id: company.id ?? null,
+    name: company.name ?? null,
+    domain: domain || null,
+    website_url: hit.url || null,
+    description: company.description ?? null,
+    founded_year: company.foundedYear ?? null,
+    headcount: company.headcount ?? null,
+    hq_location: hqLocation,
+    hq_address: hq?.address ?? null,
+    hq_city: hq?.city ?? null,
+    hq_country: hq?.country ?? null,
+    total_funding: financials?.fundingTotal ?? null,
+    total_funding_printed: formatUsdCompact(financials?.fundingTotal),
+    revenue_annual: financials?.revenueAnnual ?? null,
+    revenue_annual_printed: formatUsdCompact(financials?.revenueAnnual),
+    latest_funding_round: financials?.fundingLatestRound?.name ?? null,
+    latest_funding_date: financials?.fundingLatestRound?.date ?? null,
+    latest_funding_amount: financials?.fundingLatestRound?.amount ?? null,
+    monthly_visits: company.webTraffic?.visitsMonthly ?? null,
+  };
+
+  return {
+    organization,
+    // Mirror at the top level too: some column definitions use bare paths
+    // (`name`, `domain`) as extraction fallbacks.
+    name: organization.name,
+    domain: organization.domain,
+    // See the people envelope: the URL is useful provenance, the provider
+    // name is not — this object is handed back as the tool result.
+    source: { url: hit.url || null },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Match gating
+// ---------------------------------------------------------------------------
+
+export type ExaCompanyMatchCriteria = {
+  /** Preferred: a domain is an identity, so this is an exact match. */
+  domain?: string;
+  /** Fallback when no domain is known. Weaker — names collide. */
+  name?: string;
+};
+
+export type ExaCompanyMatch = {
+  hit: ExaCompanyHit;
+  confidence: "exact" | "high";
+  matchedOn: string;
+};
+
+export type ExaCompanyMatchOutcome =
+  | { status: "matched"; match: ExaCompanyMatch }
+  | { status: "no_match" }
+  | { status: "insufficient_criteria"; missing: string[] };
+
+/**
+ * Pick the one company we are willing to write into a CRM cell, or refuse.
+ *
+ * Domain wins outright when supplied — it is an identity, not a hint. Falling
+ * back to the name requires an exact normalized match (after stripping legal
+ * suffixes), never containment: "Example" must not match "Example Health" when
+ * those are different companies, and Exa will happily rank both.
+ */
+export function matchExaCompany(
+  hits: ExaCompanyHit[],
+  criteria: ExaCompanyMatchCriteria,
+): ExaCompanyMatchOutcome {
+  const domain = criteria.domain?.trim();
+  const name = criteria.name?.trim();
+  if (!domain && !name) {
+    return { status: "insufficient_criteria", missing: ["domain or name"] };
+  }
+
+  if (domain) {
+    for (const hit of hits) {
+      if (hit.url && domainsAgree(hit.url, domain)) {
+        return {
+          status: "matched",
+          match: { hit, confidence: "exact", matchedOn: "domain" },
+        };
+      }
+    }
+    // A domain was supplied and nothing served it. Do NOT quietly fall back to
+    // a name match: the caller told us exactly which company they meant.
+    return { status: "no_match" };
+  }
+
+  const wanted = normalizeCompany(name ?? "");
+  if (!wanted) return { status: "insufficient_criteria", missing: ["name"] };
+  const exactNameMatches = hits.filter((hit) => {
+    const candidate = hit.company.name;
+    return candidate ? normalizeCompany(candidate) === wanted : false;
+  });
+  if (exactNameMatches.length === 1) {
+    return {
+      status: "matched",
+      match: {
+        hit: exactNameMatches[0],
+        confidence: "high",
+        matchedOn: "unique_exact_name",
+      },
+    };
+  }
+  return { status: "no_match" };
+}
+
+/** Natural-language query for resolving ONE known company. */
+export function buildCompanyLookupQuery(
+  criteria: ExaCompanyMatchCriteria,
+): string {
+  if (criteria.name && criteria.domain) {
+    return `${criteria.name} (${normalizeDomain(criteria.domain)})`;
+  }
+  if (criteria.name) return criteria.name;
+  return normalizeDomain(criteria.domain ?? "");
+}