@oxygen-agent/cli 1.987.20 → 1.1010.1

package/node_modules/@oxygen/shared/dist/company-enrichment-fields.js

@@ -0,0 +1,548 @@
+// The company-enrichment FIELD CATALOG: every field the company waterfall can
+// resolve, with the vocabulary every surface shows for it.
+//
+// This is the single source of truth for the field list. The waterfall engine
+// (packages/integrations/src/company-enrichment-waterfall.ts) owns HOW a field
+// is resolved — provider lanes, derived extractors, pricing — and reads its
+// labels, column keys and data types from here; the CLI, the MCP descriptor,
+// the `company_enrich` column preset (tenant-db) and the web column picker
+// read the same catalog, so a field cannot exist on one surface and not
+// another. Three hand-copied 8-entry enums drifted independently before this
+// module existed (route, MCP schema, engine), and only the engine's was tested.
+//
+// CLIENT-SAFE LEAF: exported as the `@oxygen/shared/company-enrichment-fields`
+// subpath and imported by browser components through the tenant-db preset
+// module. It must never gain a runtime import.
+export const COMPANY_ENRICHMENT_FIELD_CATEGORIES = [
+    "identity",
+    "firmographics",
+    "funding",
+    "relationships",
+    "signals",
+    "technology",
+    "web_presence",
+];
+export const COMPANY_ENRICHMENT_FIELD_CATEGORY_LABELS = {
+    identity: "Identity",
+    firmographics: "Firmographics",
+    funding: "Funding",
+    relationships: "Relationships",
+    signals: "Signals",
+    technology: "Technology",
+    web_presence: "Web presence",
+};
+const PROFILE_THEN_FUNDING = [
+    { field: "company_profile", autoRun: true },
+    { field: "funding", autoRun: false },
+];
+export const COMPANY_ENRICHMENT_FIELD_DEFINITIONS = [
+    // ── identity ─────────────────────────────────────────────────────────────
+    {
+        field: "domain",
+        label: "Company domain",
+        category: "identity",
+        description: "The company's website domain, resolved from its name or LinkedIn page.",
+        columnKey: "company_domain",
+        dataType: "text",
+        semanticType: "company.domain",
+        derivedFrom: [],
+    },
+    {
+        field: "linkedin_url",
+        label: "Company LinkedIn URL",
+        category: "identity",
+        description: "The company's LinkedIn page, resolved from its domain or name.",
+        columnKey: "company_linkedin_url",
+        dataType: "text",
+        semanticType: "company.linkedin_url",
+        derivedFrom: [],
+    },
+    // ── firmographics ────────────────────────────────────────────────────────
+    {
+        field: "headcount",
+        label: "Headcount",
+        category: "firmographics",
+        description: "Employee count, exact when the provider has it, otherwise the size band.",
+        columnKey: "company_headcount",
+        dataType: "text",
+        semanticType: "company.employee_count",
+        derivedFrom: [],
+    },
+    {
+        field: "industry",
+        label: "Industry",
+        category: "firmographics",
+        description: "The industry the company lists for itself.",
+        columnKey: "company_industry",
+        dataType: "text",
+        semanticType: "company.industry",
+        derivedFrom: [],
+    },
+    {
+        field: "company_profile",
+        label: "Company profile",
+        category: "firmographics",
+        description: "The whole provider profile as one record; the free fields below are read out of it.",
+        columnKey: "company_profile",
+        dataType: "jsonb",
+        semanticType: null,
+        derivedFrom: [],
+    },
+    {
+        field: "description",
+        label: "Description",
+        category: "firmographics",
+        description: "The company's own about text, read from the profile already fetched.",
+        columnKey: "company_description",
+        dataType: "text",
+        semanticType: "company.description",
+        derivedFrom: PROFILE_THEN_FUNDING,
+    },
+    {
+        field: "founded_year",
+        label: "Founded year",
+        category: "firmographics",
+        description: "The year the company was founded, read from the profile already fetched.",
+        columnKey: "company_founded_year",
+        dataType: "numeric",
+        semanticType: "company.founded_year",
+        derivedFrom: PROFILE_THEN_FUNDING,
+    },
+    {
+        field: "hq_address",
+        label: "HQ address",
+        category: "firmographics",
+        description: "Headquarters street, city and country as one line, from the profile already fetched.",
+        columnKey: "company_hq_address",
+        dataType: "text",
+        semanticType: "company.hq_location",
+        derivedFrom: PROFILE_THEN_FUNDING,
+    },
+    {
+        field: "hq_country",
+        label: "HQ country",
+        category: "firmographics",
+        description: "Headquarters country, from the profile already fetched.",
+        columnKey: "company_hq_country",
+        dataType: "text",
+        semanticType: "company.hq_country",
+        derivedFrom: PROFILE_THEN_FUNDING,
+    },
+    {
+        field: "company_type",
+        label: "Company type",
+        category: "firmographics",
+        description: "Privately held, public, non-profit and the like, from the profile already fetched.",
+        columnKey: "company_type",
+        dataType: "text",
+        semanticType: null,
+        derivedFrom: PROFILE_THEN_FUNDING,
+    },
+    {
+        field: "specialties",
+        label: "Specialties",
+        category: "firmographics",
+        description: "The specialties or keywords the company lists, from the profile already fetched.",
+        columnKey: "company_specialties",
+        dataType: "jsonb",
+        semanticType: "company.specialties",
+        derivedFrom: [{ field: "company_profile", autoRun: true }],
+    },
+    // ── funding ──────────────────────────────────────────────────────────────
+    {
+        field: "funding",
+        label: "Funding",
+        category: "funding",
+        description: "The raw funding record from a funding provider: rounds, amounts, investors, total.",
+        columnKey: "company_funding",
+        dataType: "jsonb",
+        semanticType: null,
+        derivedFrom: [],
+    },
+    {
+        field: "revenue",
+        label: "Revenue (estimate)",
+        category: "funding",
+        description: "Estimated annual revenue, a figure when the source has one, otherwise a range band.",
+        columnKey: "company_revenue",
+        dataType: "text",
+        semanticType: "company.revenue",
+        derivedFrom: [],
+    },
+    {
+        field: "funding_stage",
+        label: "Funding stage",
+        category: "funding",
+        description: "The latest round's type, e.g. Seed or Series B; free when the LinkedIn page lists funding.",
+        columnKey: "company_funding_stage",
+        dataType: "text",
+        semanticType: null,
+        derivedFrom: PROFILE_THEN_FUNDING,
+    },
+    {
+        field: "latest_funding_round",
+        label: "Latest funding round",
+        category: "funding",
+        description: "Date, amount, round type and lead investors of the most recent round.",
+        columnKey: "company_latest_funding_round",
+        dataType: "jsonb",
+        semanticType: null,
+        derivedFrom: PROFILE_THEN_FUNDING,
+    },
+    {
+        field: "total_funding",
+        label: "Total funding",
+        category: "funding",
+        description: "Total raised to date in USD, from a funding provider (LinkedIn does not publish it).",
+        columnKey: "company_total_funding",
+        dataType: "numeric",
+        semanticType: "company.funding_raised",
+        derivedFrom: [
+            { field: "funding", autoRun: true },
+            { field: "company_profile", autoRun: false },
+        ],
+    },
+    {
+        field: "funding_rounds_count",
+        label: "Number of funding rounds",
+        category: "funding",
+        description: "How many rounds the company has raised.",
+        columnKey: "company_funding_rounds_count",
+        dataType: "numeric",
+        semanticType: null,
+        derivedFrom: PROFILE_THEN_FUNDING,
+    },
+    {
+        field: "investors",
+        label: "Investors",
+        category: "funding",
+        description: "Named investors across the rounds a provider knows about.",
+        columnKey: "company_investors",
+        dataType: "jsonb",
+        semanticType: null,
+        derivedFrom: PROFILE_THEN_FUNDING,
+    },
+    // ── relationships ────────────────────────────────────────────────────────
+    {
+        field: "competitors",
+        label: "Competitors",
+        category: "relationships",
+        description: "Named competitors from a funding-intelligence provider; LinkedIn's similar pages when the profile is already on the row.",
+        columnKey: "company_competitors",
+        dataType: "jsonb",
+        semanticType: null,
+        derivedFrom: [
+            { field: "funding", autoRun: false },
+            { field: "company_profile", autoRun: false },
+        ],
+        availability: "coming_soon",
+    },
+    {
+        field: "corporate_structure",
+        label: "Corporate structure",
+        category: "relationships",
+        description: "Parent company and subsidiaries as one record.",
+        columnKey: "company_corporate_structure",
+        dataType: "jsonb",
+        semanticType: null,
+        derivedFrom: [],
+        availability: "coming_soon",
+    },
+    {
+        field: "parent_company",
+        label: "Parent company",
+        category: "relationships",
+        description: "The company that owns this one, read from the corporate structure lookup.",
+        columnKey: "company_parent_company",
+        dataType: "text",
+        semanticType: null,
+        derivedFrom: [{ field: "corporate_structure", autoRun: true }],
+        availability: "coming_soon",
+    },
+    {
+        field: "subsidiaries",
+        label: "Subsidiaries",
+        category: "relationships",
+        description: "Companies this one owns, read from the corporate structure lookup.",
+        columnKey: "company_subsidiaries",
+        dataType: "jsonb",
+        semanticType: null,
+        derivedFrom: [{ field: "corporate_structure", autoRun: true }],
+        availability: "coming_soon",
+    },
+    {
+        field: "acquisitions",
+        label: "Acquisitions",
+        category: "relationships",
+        description: "Companies this one has acquired, with dates and sources.",
+        columnKey: "company_acquisitions",
+        dataType: "jsonb",
+        semanticType: null,
+        derivedFrom: [{ field: "funding", autoRun: false }],
+        availability: "coming_soon",
+    },
+    // ── signals ──────────────────────────────────────────────────────────────
+    {
+        field: "news",
+        label: "News",
+        category: "signals",
+        description: "Recent dated news items about the company.",
+        columnKey: "company_news",
+        dataType: "jsonb",
+        semanticType: null,
+        derivedFrom: [{ field: "funding", autoRun: false }],
+        availability: "coming_soon",
+    },
+    {
+        field: "hiring_signals",
+        label: "Hiring signals",
+        category: "signals",
+        description: "The raw open-roles payload from a jobs provider.",
+        columnKey: "company_hiring_signals",
+        dataType: "jsonb",
+        semanticType: null,
+        derivedFrom: [],
+    },
+    {
+        field: "job_openings",
+        label: "Job openings",
+        category: "signals",
+        description: "Open roles from the hiring lookup, listed (up to ten) with a count.",
+        columnKey: "company_job_openings",
+        dataType: "jsonb",
+        semanticType: null,
+        derivedFrom: [{ field: "hiring_signals", autoRun: true }],
+    },
+    // ── technology ───────────────────────────────────────────────────────────
+    {
+        field: "technologies",
+        label: "Tech stack",
+        category: "technology",
+        description: "Technologies the company runs, from its job postings (with confidence and first/last-seen dates) or its website.",
+        columnKey: "company_technologies",
+        dataType: "jsonb",
+        semanticType: null,
+        derivedFrom: [],
+    },
+    {
+        field: "technology_check",
+        label: "Technology check",
+        category: "technology",
+        description: "Yes or no per technology you name, checked against the detected stack.",
+        columnKey: "company_technology_check",
+        dataType: "jsonb",
+        semanticType: null,
+        derivedFrom: [{ field: "technologies", autoRun: true }],
+        requires: "check_technologies",
+    },
+    // ── web presence ─────────────────────────────────────────────────────────
+    {
+        field: "logo_url",
+        label: "Logo",
+        category: "web_presence",
+        description: "The company logo image URL, from the profile already fetched.",
+        columnKey: "company_logo_url",
+        dataType: "text",
+        semanticType: "company.logo_url",
+        derivedFrom: [{ field: "company_profile", autoRun: true }],
+    },
+    {
+        field: "crunchbase_url",
+        label: "Crunchbase URL",
+        category: "web_presence",
+        description: "The company's Crunchbase page; free when the LinkedIn page links it, otherwise one web search.",
+        columnKey: "company_crunchbase_url",
+        dataType: "text",
+        semanticType: null,
+        derivedFrom: [
+            { field: "company_profile", autoRun: false },
+            { field: "funding", autoRun: false },
+        ],
+        availability: "coming_soon",
+    },
+    {
+        field: "github_url",
+        label: "GitHub URL",
+        category: "web_presence",
+        description: "The company's GitHub organization, found by one site-scoped web search.",
+        columnKey: "company_github_url",
+        dataType: "text",
+        semanticType: null,
+        derivedFrom: [],
+        availability: "coming_soon",
+    },
+    {
+        field: "facebook_url",
+        label: "Facebook URL",
+        category: "web_presence",
+        description: "The company's Facebook page, found by one site-scoped web search.",
+        columnKey: "company_facebook_url",
+        dataType: "text",
+        semanticType: "company.facebook_url",
+        derivedFrom: [{ field: "funding", autoRun: false }],
+        availability: "coming_soon",
+    },
+    {
+        field: "instagram_url",
+        label: "Instagram URL",
+        category: "web_presence",
+        description: "The company's Instagram profile, found by one site-scoped web search.",
+        columnKey: "company_instagram_url",
+        dataType: "text",
+        semanticType: "company.instagram_url",
+        derivedFrom: [],
+        availability: "coming_soon",
+    },
+    {
+        field: "youtube_url",
+        label: "YouTube URL",
+        category: "web_presence",
+        description: "The company's YouTube channel, found by one site-scoped web search.",
+        columnKey: "company_youtube_url",
+        dataType: "text",
+        semanticType: null,
+        derivedFrom: [],
+        availability: "coming_soon",
+    },
+];
+export const COMPANY_ENRICHMENT_FIELD_KEYS = COMPANY_ENRICHMENT_FIELD_DEFINITIONS.map((definition) => definition.field);
+const DEFINITIONS_BY_FIELD = new Map(COMPANY_ENRICHMENT_FIELD_DEFINITIONS.map((definition) => [definition.field, definition]));
+export function isCompanyEnrichmentFieldKey(value) {
+    return DEFINITIONS_BY_FIELD.has(value);
+}
+export function companyEnrichmentFieldDefinition(field) {
+    const definition = DEFINITIONS_BY_FIELD.get(field);
+    if (!definition)
+        throw new Error(`Unknown company enrichment field "${field}".`);
+    return definition;
+}
+/** D51: a field parked `coming_soon` has no lane, no picker group and is refused by `--fields`. */
+export function isComingSoonCompanyEnrichmentField(field) {
+    return companyEnrichmentFieldDefinition(field).availability === "coming_soon";
+}
+/** A field whose value is read out of another field's payload, never a provider call of its own. */
+export function isDerivedCompanyEnrichmentField(field) {
+    return companyEnrichmentFieldDefinition(field).derivedFrom.length > 0;
+}
+/**
+ * What `find company` resolves when the caller names no fields. Identity plus
+ * the firmographics that cost nothing beyond the one profile lookup the
+ * headcount/industry lanes already make; funding, relationship and web-presence
+ * fields stay opt-in because each adds a priced lane.
+ */
+export const DEFAULT_COMPANY_FIND_FIELDS = [
+    "domain",
+    "linkedin_url",
+    "headcount",
+    "industry",
+    "description",
+    "founded_year",
+    "hq_country",
+];
+/**
+ * What `columns add --preset company_enrich` creates when the caller names no
+ * fields: the identity/firmographic set plus the full profile and what it says
+ * about the company. Every lane-priced relationship, funding, signal,
+ * technology and web-presence field is opt-in through `--fields`, so the
+ * default bundle's per-row ceiling stays the profile chain's.
+ *
+ * Funding stage and latest round left the default on 2026-09-24 (founder, D55):
+ * the profile lane is Blitz first now, and Blitz's company profile carries no
+ * funding, so on the rows Blitz answers those two columns would sit empty. They
+ * live in the Funding details group instead.
+ */
+export const DEFAULT_COMPANY_PRESET_FIELDS = [
+    "domain",
+    "linkedin_url",
+    "headcount",
+    "industry",
+    "company_profile",
+    "description",
+    "founded_year",
+    "hq_country",
+];
+/**
+ * The opt-in company fields, grouped the way a customer asks for them ("add
+ * competitors", "add their tech stack"). Every surface that offers a company
+ * field beyond the default bundle reads THIS list: the enrichment column catalog
+ * (`oxygen enrichment catalog`, `oxygen_enrichment_catalog`), the web add-column
+ * picker, and the catalog pricing. Adding a group adds its fields to the SAME
+ * company enrichment column — re-applying the bundle widens the existing
+ * column's field list instead of creating a second paid column.
+ */
+export const COMPANY_ENRICHMENT_FIELD_GROUPS = [
+    {
+        id: "profile_details",
+        label: "Company profile details",
+        description: "HQ address, company type, specialties and logo, read from the company profile the bundle already fetches.",
+        fields: ["hq_address", "company_type", "specialties", "logo_url"],
+        cost: "included",
+    },
+    {
+        id: "funding_details",
+        label: "Funding details",
+        description: "Funding stage, latest round, total raised, number of rounds and investors, with the full funding history kept alongside.",
+        fields: ["funding", "revenue", "funding_stage", "latest_funding_round", "total_funding", "funding_rounds_count", "investors"],
+        cost: "extra",
+    },
+    {
+        id: "job_openings",
+        label: "Job openings",
+        description: "The roles each account is hiring for, as a count and a list.",
+        fields: ["hiring_signals", "job_openings"],
+        cost: "extra",
+    },
+    {
+        id: "tech_stack",
+        label: "Tech stack",
+        description: "The technologies each account runs, from its job postings (with confidence and first/last seen) or its website.",
+        fields: ["technologies"],
+        cost: "extra",
+    },
+    {
+        id: "technology_check",
+        label: "Technology check",
+        description: "Yes or no per account for each technology you name, such as HubSpot or Salesforce.",
+        fields: ["technology_check"],
+        cost: "extra",
+        requires: "check_technologies",
+    },
+];
+export function companyEnrichmentFieldGroup(id) {
+    return COMPANY_ENRICHMENT_FIELD_GROUPS.find((group) => group.id === id) ?? null;
+}
+/**
+ * Parse a comma-separated or array field list against the catalog. Returns the
+ * unique, lowercased keys in request order, or throws naming every unknown
+ * entry with the supported list — never a silent fallback to a default set,
+ * which is how `--fields tech,hiring,profile` once ran the four default fields
+ * and billed for an answer nobody asked for (OXP-7.2.9).
+ */
+export function parseCompanyEnrichmentFieldList(value) {
+    const entries = Array.isArray(value)
+        ? value
+        : typeof value === "string"
+            ? value.split(",")
+            : [];
+    const cleaned = entries
+        .map((entry) => (typeof entry === "string" ? entry.trim().toLowerCase() : ""))
+        .filter((entry) => entry.length > 0);
+    const fields = [];
+    const unknown = [];
+    const coming_soon = [];
+    for (const entry of cleaned) {
+        if (isCompanyEnrichmentFieldKey(entry)) {
+            if (isComingSoonCompanyEnrichmentField(entry)) {
+                if (!coming_soon.includes(entry))
+                    coming_soon.push(entry);
+            }
+            else if (!fields.includes(entry)) {
+                fields.push(entry);
+            }
+        }
+        else if (!unknown.includes(entry)) {
+            unknown.push(entry);
+        }
+    }
+    return { fields, unknown, coming_soon };
+}