@coldiq/mcp 0.3.4 → 0.3.5

package/dist/utils/selection-insight.js

@@ -0,0 +1,295 @@
+import { providerDisplayName } from './provider-display.js';
+// ---------------------------------------------------------------------------
+// Curated data-quality strengths, keyed by capability → providerId.
+// Each value is a noun phrase that slots into "… for its <strength>". Phrasing
+// is descriptive (deep / strong / broad / specialized), NOT superlative, so it
+// stays defensible on the fallthrough path too.
+// ---------------------------------------------------------------------------
+const STRENGTHS = {
+    search_companies: {
+        companyenrich: 'broad firmographic coverage with full-text company matching',
+        apollo: 'an extensive global company database',
+        fullenrich: 'rich firmographic data with strong international coverage',
+        pdl: 'a large, structured global company dataset',
+        signalbase: 'fast firmographic search across keywords and industries',
+        blitzapi: 'LinkedIn-sourced company data',
+        limadata: 'LinkedIn-based company discovery',
+        predictleads: 'discovery scoped tightly by location and company size',
+        theirstack: 'deep technographic and buying-intent coverage',
+        sumble: 'technology- and keyword-driven company discovery',
+        'limadata-prospect-filter': 'LinkedIn headcount-bucketed prospecting',
+        'limadata-prospect-url': 'discovery straight from a LinkedIn Sales Navigator search',
+        'linkupapi-search': 'live LinkedIn company search',
+        'linkupapi-fundraising': 'a dedicated index of recently-funded companies',
+        'linkupapi-hiring': 'a dedicated index of actively-hiring companies',
+        'prospeo-search-company': 'keyword, industry and geo company search',
+        'ai-ark-companies': 'multi-filter company discovery',
+    },
+    find_people: {
+        leadsfactory: 'company-scoped contact discovery by persona',
+        apollo: 'an extensive global contact database',
+        pdl: 'a large, structured global people dataset',
+        companyenrich: 'domain-scoped employee lookups',
+        'linkupapi-search-profiles': 'live LinkedIn profile search',
+        'sumble-people-find': 'org-scoped people search by job function',
+        'prospeo-search-person': 'title- and company-based people search',
+        'ai-ark-people': 'multi-filter people discovery',
+        'fullenrich-people-search': 'domain-scoped people search',
+        'findymail-search-employees': 'domain-scoped employee discovery',
+    },
+    find_email: {
+        prospeo: 'strong work-email coverage',
+        fullenrich: 'strong international email coverage, especially across Europe',
+        findymail: 'high-accuracy verified work emails',
+        icypeas: 'broad email-finding coverage',
+        'limadata-work-email': 'name-and-domain work-email lookup',
+        blitzapi: 'LinkedIn-URL–based email finding',
+        'limadata-work-email-linkedin': 'LinkedIn-URL–based work-email lookup',
+        linkupapi: 'LinkedIn-sourced email finding',
+    },
+    find_emails: {
+        prospeo: 'strong work-email coverage',
+        fullenrich: 'strong international email coverage, especially across Europe',
+        findymail: 'high-accuracy verified work emails',
+        icypeas: 'broad email-finding coverage',
+        'limadata-work-email': 'name-and-domain work-email lookup',
+        blitzapi: 'LinkedIn-URL–based email finding',
+        'limadata-work-email-linkedin': 'LinkedIn-URL–based work-email lookup',
+        linkupapi: 'LinkedIn-sourced email finding',
+    },
+    verify_email: {
+        findymail: 'reliable deliverability verification',
+        icypeas: 'broad email verification',
+        instantly: 'deliverability-focused verification',
+        'linkupapi-validate': 'LinkedIn-aware email validation',
+    },
+    find_phone: {
+        findymail: 'verified mobile-number coverage',
+        limadata: 'phone lookup by LinkedIn URL or name + company',
+        'ai-ark': 'phone lookup across multiple identifiers',
+    },
+    enrich_company: {
+        companyenrich: 'broad firmographic enrichment from a domain',
+        apollo: 'deep firmographic enrichment',
+        pdl: 'structured firmographic data',
+        findymail: 'domain-based company enrichment',
+        wiza: 'company enrichment from name or domain',
+        limadata: 'LinkedIn-based company enrichment',
+        prospeo: 'company enrichment',
+        companyenrich_props: 'company enrichment from name or LinkedIn',
+        blitzapi: 'LinkedIn-URL company enrichment',
+        icypeas: 'LinkedIn-URL company enrichment',
+        builtwith: 'technology-stack detection for a domain',
+        openmart: 'local-business firmographics',
+        'linkupapi-by-domain': 'live LinkedIn company data',
+        'linkupapi-by-url': 'live LinkedIn company data',
+    },
+    enrich_person: {
+        'linkupapi-profile-enrich': 'live LinkedIn profile enrichment',
+        'linkupapi-email-reverse': 'reverse-email lookup from LinkedIn data',
+        'pdl-person-enrich': 'structured person enrichment',
+        'apollo-people-match': 'deep person enrichment',
+        'blitzapi-reverse-email': 'reverse-email profile lookup',
+        'findymail-business-profile': 'LinkedIn profile enrichment',
+        'findymail-reverse-email': 'reverse-email lookup',
+        'icypeas-scrape-profile': 'LinkedIn profile scraping',
+        'icypeas-url-search-profile': 'profile lookup by name and company',
+        'ai-ark-reverse-lookup': 'reverse lookup from email or phone',
+        'icypeas-reverse-email-lookup': 'reverse-email lookup',
+        'pdl-person-identify': 'person identity resolution',
+    },
+    search_web: {
+        serper: 'fast Google search results',
+        exa: 'neural, meaning-based web search',
+        limadata: 'general web search',
+        jina: 'web search and page reading',
+    },
+    search_jobs: {
+        career_site_jobs: 'jobs sourced directly from company career sites',
+        linkedin_jobs_api: 'LinkedIn job listings',
+        'theirstack-jobs': 'jobs enriched with company and tech-stack data',
+    },
+    search_ads: {
+        google_ads: 'Google ad-transparency data',
+        linkedin_ad_library: 'LinkedIn Ad Library coverage',
+        meta_ads: 'Meta (Facebook/Instagram) ad-library coverage',
+        twitter_ads: 'X ad coverage',
+        reddit_ads: 'Reddit ad coverage',
+    },
+    search_places: {
+        openmart: 'rich local-business data across the US, CA, AU, PR and NZ',
+        google_maps: 'broad global places coverage from Google Maps',
+    },
+    get_place_reviews: {
+        google_maps_reviews: 'Google Maps review data',
+    },
+    find_influencers: {
+        influencers_similar: 'lookalike creator discovery from a seed handle',
+        influencers_discovery: 'creator discovery by topic and audience',
+    },
+    search_reddit: {
+        reddit: 'Reddit post and comment search',
+    },
+    find_signals: {
+        'signalbase-funding': 'real-time funding-round signals',
+        'signalbase-acquisition': 'acquisition signals',
+        'signalbase-hiring': 'hiring signals',
+        'signalbase-job-change': 'job-change signals',
+        'theirstack-hiring': 'hiring signals from job-posting data',
+        'theirstack-intent-discovery': 'buying-intent discovery',
+        'theirstack-buying-intents': 'buying-intent signals from tech and job data',
+        'predictleads-financing': 'financing-event signals',
+        'predictleads-news': 'company-news signals',
+        'predictleads-startup-posts': 'startup-announcement signals',
+    },
+    fetch_page_content: {
+        'exa-contents': 'clean page-content extraction',
+    },
+};
+// ---------------------------------------------------------------------------
+// Per-capability noun used in the plain fallback line ("X matched this <noun>").
+// ---------------------------------------------------------------------------
+const CAPABILITY_NOUN = {
+    search_companies: 'company search',
+    find_people: 'people search',
+    find_email: 'email lookup',
+    find_emails: 'email lookup',
+    verify_email: 'email verification',
+    find_phone: 'phone lookup',
+    enrich_company: 'company enrichment',
+    enrich_person: 'person enrichment',
+    search_web: 'web search',
+    search_jobs: 'job search',
+    search_ads: 'ad search',
+    search_places: 'places search',
+    get_place_reviews: 'reviews lookup',
+    find_influencers: 'influencer search',
+    search_reddit: 'Reddit search',
+    search_seo: 'SEO lookup',
+    find_signals: 'signal search',
+    fetch_page_content: 'page fetch',
+};
+// ---------------------------------------------------------------------------
+// Signal detection — which input dimensions drove routing, in human terms.
+// Ordered most-distinctive-first so signals[0] is the routing-relevant one.
+// ---------------------------------------------------------------------------
+function arr(v) {
+    return Array.isArray(v) && v.length > 0;
+}
+function num(v) {
+    return typeof v === 'number';
+}
+function str(v) {
+    return typeof v === 'string' && v.length > 0;
+}
+function detectSignals(capability, input) {
+    const out = [];
+    const push = (cond, label) => {
+        if (cond && !out.includes(label))
+            out.push(label);
+    };
+    switch (capability) {
+        case 'search_companies':
+            push(arr(input.technologies), 'tech-stack filter');
+            push(arr(input.funding_stages) ||
+                num(input.min_funding_amount) || num(input.max_funding_amount) ||
+                num(input.min_funding_year) || num(input.max_funding_year), 'funding filter');
+            push(num(input.min_revenue) || num(input.max_revenue), 'revenue filter');
+            push(arr(input.exclude_domains) || arr(input.exclude_industries) || arr(input.exclude_countries), 'exclusion list');
+            push(num(input.min_workforce_growth_pct), 'workforce-growth filter');
+            push(input.is_hiring === true, 'hiring signal');
+            push(num(input.min_founded_year) || num(input.max_founded_year), 'founding-year filter');
+            push(num(input.min_employees) || num(input.max_employees), 'company-size filter');
+            push(str(input.linkedin_search_url), 'LinkedIn Sales Navigator URL');
+            push(arr(input.industries), 'industry filter');
+            push(arr(input.keywords), 'keyword search');
+            push(arr(input.countries) || arr(input.locations), 'geo filter');
+            break;
+        case 'find_people':
+            push(arr(input.company_domains), 'company-domain filter');
+            push(arr(input.company_linkedin_urls), 'company LinkedIn filter');
+            push(arr(input.job_titles), 'job-title filter');
+            push(arr(input.seniorities), 'seniority filter');
+            push(arr(input.keywords), 'keyword search');
+            push(arr(input.locations), 'geo filter');
+            break;
+        case 'find_email':
+            push(str(input.linkedin_url), 'LinkedIn URL');
+            push(str(input.domain) || str(input.company_name), 'name + company');
+            break;
+        case 'find_emails': {
+            const people = input.people ?? [];
+            push(people.some((p) => str(p.linkedin_url)), 'LinkedIn URLs');
+            push(people.some((p) => str(p.domain)), 'name + domain');
+            break;
+        }
+        case 'enrich_company':
+            push(str(input.domain), 'company domain');
+            push(str(input.linkedin_url), 'LinkedIn URL');
+            push(str(input.name), 'company name');
+            break;
+        case 'enrich_person':
+            push(str(input.email), 'email');
+            push(str(input.linkedin_url), 'LinkedIn URL');
+            push(str(input.first_name) && str(input.last_name), 'name + company');
+            break;
+        case 'find_signals':
+            if (str(input.signal_type))
+                out.push(`${String(input.signal_type)} signals`);
+            push(arr(input.companies) || arr(input.domains), 'company filter');
+            break;
+        case 'search_jobs':
+            push(arr(input.technologies), 'tech-stack filter');
+            push(arr(input.company_domains), 'company-domain filter');
+            push(arr(input.job_titles) || arr(input.keywords), 'role filter');
+            push(arr(input.locations), 'geo filter');
+            break;
+        case 'search_ads':
+            push(arr(input.search_urls), 'LinkedIn Ad Library URL');
+            push(arr(input.domains) || arr(input.advertiser_ids), 'advertiser filter');
+            push(str(input.query), 'keyword search');
+            break;
+        default:
+            // Other capabilities: no curated signal vocabulary — routing is single-source
+            // or non-discriminating, so leave signals empty and rely on the base strength.
+            break;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+/**
+ * Build a data-quality-framed reason for why `providerId` was selected for
+ * `capability` given `input`. Returns undefined only when there is genuinely
+ * nothing safe to say.
+ */
+export function buildSelectionInsight(capability, providerId, input, ctx) {
+    const name = providerDisplayName(providerId);
+    const signals = detectSignals(capability, input);
+    // User pinned this provider — it wasn't our choice, so don't claim it was.
+    if (ctx.pinnedByUser) {
+        return { insight: `Used ${name} as requested.`, signals };
+    }
+    const strength = STRENGTHS[capability]?.[providerId];
+    const noun = CAPABILITY_NOUN[capability] ?? 'request';
+    const primary = signals[0];
+    // No curated edge for this provider — emit a plain, true line, never invent one.
+    if (!strength) {
+        const insight = primary
+            ? `${name} matched your ${primary} for this ${noun}.`
+            : `${name} matched this ${noun}.`;
+        return { insight, signals };
+    }
+    // Fallthrough: higher-ranked providers returned nothing. Soften — state the
+    // coverage fact without implying we judged it the single best fit upfront.
+    if (ctx.wasFallback) {
+        return { insight: `${name} returned the match here, with ${strength}.`, signals };
+    }
+    // Capability routing: chosen because it is best-suited to these inputs.
+    const insight = primary
+        ? `Routed to ${name} for its ${strength}, matched to your ${primary}.`
+        : `Routed to ${name} for its ${strength}.`;
+    return { insight, signals };
+}
+//# sourceMappingURL=selection-insight.js.map

package/dist/utils/selection-insight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selection-insight.js","sourceRoot":"","sources":["../../src/utils/selection-insight.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldiq/mcp",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "type": "module",
   "main": "dist/index.js",
   "bin": {

package/src/executor.ts

@@ -1,11 +1,19 @@
 import { callApi } from './client.js'
 import { getProviders, getSearchWebProviders } from './registry.js'
 import type { Capability, ProviderEntry } from './registry.js'
+import { providerDisplayName } from './utils/provider-display.js'
+import { buildSelectionInsight } from './utils/selection-insight.js'
 
 export interface ExecutionResult {
   data: unknown
   _meta: {
     provider: string
+    /** Clean branded display name for `provider` (never a raw slug or "Apify"). */
+    provider_name?: string
+    /** Data-quality-framed reason this provider was selected, for the chat surface. */
+    selection_insight?: string
+    /** Input dimensions that drove routing (e.g. ["tech-stack filter"]), for UI chips. */
+    selection_signals?: string[]
     latencyMs: number
     matchedFrom?: Record<string, string>
     /** Net ColdIQ credits charged for this call (parsed from `X-ColdIQ-Credits-Charged`). */
@@ -306,7 +314,21 @@ export async function executeWithFallback(
 
     if (hasResult) {
       log(`${capability} → ${provider.id} ✓ (${result.latencyMs}ms)`)
-      const meta: ExecutionResult['_meta'] = { provider: provider.id, latencyMs: result.latencyMs }
+      const meta: ExecutionResult['_meta'] = {
+        provider: provider.id,
+        provider_name: providerDisplayName(provider.id),
+        latencyMs: result.latencyMs,
+      }
+      // `errors.length > 0` here means higher-ranked applicable providers returned
+      // nothing and we fell through — soften the insight wording accordingly.
+      const insight = buildSelectionInsight(capability, provider.id, input, {
+        wasFallback: errors.length > 0,
+        pinnedByUser: isConstrained,
+      })
+      if (insight) {
+        meta.selection_insight = insight.insight
+        if (insight.signals.length > 0) meta.selection_signals = insight.signals
+      }
       if (options?.matchedFrom && Object.keys(options.matchedFrom).length > 0) {
         meta.matchedFrom = options.matchedFrom
       }

package/src/tools/find-emails.ts

@@ -2,6 +2,8 @@ import { z } from 'zod'
 import { callApi, type ApiResponse } from '../client.js'
 import { executeWithFallback, isExecutionError } from '../executor.js'
 import { resolvePreferredProviders, buildAllFailedError, FIND_EMAILS_PROVIDERS } from '../utils/provider-resolver.js'
+import { providerDisplayName } from '../utils/provider-display.js'
+import { buildSelectionInsight } from '../utils/selection-insight.js'
 
 // Single-find_email registry providers that the bulk pipeline does NOT already cover.
 // Used as a fallback waterfall for residual misses after Prospeo + FullEnrich + Findymail + Icypeas.
@@ -462,6 +464,46 @@ export async function findEmailsHandler(input: Record<string, unknown>) {
     meta.matchedFrom = resolved.matchedFrom
   }
 
+  // Batch-level selection insight: the per-person waterfall returns a provider per
+  // result, so attribute the batch to the provider that resolved the most emails.
+  // Prospeo is the primary bulk step (Step 1); anything else means we relied on a
+  // fallback step, so soften the wording.
+  if (found > 0) {
+    const winCounts = new Map<string, number>()
+    for (const r of results) {
+      if (r.email && r.provider) winCounts.set(r.provider, (winCounts.get(r.provider) ?? 0) + 1)
+    }
+    // Tie-break deterministically by waterfall rank: scan in FIND_EMAILS_PROVIDERS
+    // order and replace only on a strictly greater count, so an equal-count primary
+    // (Prospeo, Step 1) is never displaced by a later fallback step — keeps the
+    // attribution stable regardless of people-input order.
+    let dominant: string | undefined
+    let best = 0
+    for (const id of FIND_EMAILS_PROVIDERS) {
+      const count = winCounts.get(id) ?? 0
+      if (count > best) { best = count; dominant = id }
+    }
+    if (dominant) {
+      const insight = buildSelectionInsight('find_emails', dominant, restInput, {
+        // Steps 2-4 only run on Prospeo's misses, so a non-Prospeo winner is a
+        // genuine fallthrough — unless the caller pinned providers (no Prospeo step),
+        // in which case the pinnedByUser branch governs the wording anyway.
+        wasFallback: dominant !== 'prospeo' && !isConstrained,
+        pinnedByUser: isConstrained,
+      })
+      if (insight) {
+        meta.selection_insight = insight.insight
+        if (insight.signals.length > 0) meta.selection_signals = insight.signals
+      }
+    }
+  }
+
+  // Surface branded provider names per person so users never see a raw slug.
+  const brandedResults = results.map((r) => ({
+    ...r,
+    provider_name: r.provider ? providerDisplayName(r.provider) : null,
+  }))
+
   // Surface the silent-failure case the user reported: 200 OK with all-nulls is misleading
   // when the nulls were caused by provider failures rather than legitimate no-coverage.
   const isError = batchStatus === 'failed'
@@ -470,7 +512,7 @@ export async function findEmailsHandler(input: Record<string, unknown>) {
     content: [
       {
         type: 'text' as const,
-        text: JSON.stringify({ data: { results, found, total: people.length }, _meta: meta }),
+        text: JSON.stringify({ data: { results: brandedResults, found, total: people.length }, _meta: meta }),
       },
     ],
     ...(isError ? { isError: true } : {}),

package/src/utils/provider-display.ts

@@ -0,0 +1,150 @@
+// ---------------------------------------------------------------------------
+// Provider display names
+// ---------------------------------------------------------------------------
+//
+// Internal provider IDs (registry.ts + the find_emails waterfall) are a mix of
+// clean vendor names ("apollo"), already-branded slugs ("reddit_ads"), and ugly
+// internal slugs ("limadata-work-email"). User-facing surfaces — the selection
+// insight and `_meta.provider_name` — must show a clean branded label instead.
+//
+// Naming the real data product (FullEnrich, TheirStack, …) is intentional: it IS
+// the ColdIQ "we picked the best tool" intelligence on display. The ONLY thing
+// that must never surface is the Apify backend — and since no ID contains the
+// word "Apify", that constraint is satisfied by mapping the Apify-backed scrapers
+// to their branded data-source name (e.g. "Reddit Ads").
+// ---------------------------------------------------------------------------
+
+const DISPLAY_NAMES: Record<string, string> = {
+  // --- B2B data vendors (shared across capabilities) -----------------------
+  companyenrich: 'CompanyEnrich',
+  companyenrich_props: 'CompanyEnrich',
+  apollo: 'Apollo',
+  'apollo-people-match': 'Apollo',
+  fullenrich: 'FullEnrich',
+  'fullenrich-people-search': 'FullEnrich',
+  pdl: 'People Data Labs',
+  'pdl-person-enrich': 'People Data Labs',
+  'pdl-person-identify': 'People Data Labs',
+  signalbase: 'SignalBase',
+  'signalbase-funding': 'SignalBase',
+  'signalbase-acquisition': 'SignalBase',
+  'signalbase-hiring': 'SignalBase',
+  'signalbase-job-change': 'SignalBase',
+  blitzapi: 'BlitzAPI',
+  'blitzapi-reverse-email': 'BlitzAPI',
+  limadata: 'LimaData',
+  'limadata-prospect-filter': 'LimaData',
+  'limadata-prospect-url': 'LimaData',
+  'limadata-work-email': 'LimaData',
+  'limadata-work-email-linkedin': 'LimaData',
+  predictleads: 'PredictLeads',
+  'predictleads-financing': 'PredictLeads',
+  'predictleads-news': 'PredictLeads',
+  'predictleads-startup-posts': 'PredictLeads',
+  theirstack: 'TheirStack',
+  'theirstack-jobs': 'TheirStack',
+  'theirstack-hiring': 'TheirStack',
+  'theirstack-intent-discovery': 'TheirStack',
+  'theirstack-buying-intents': 'TheirStack',
+  sumble: 'Sumble',
+  'sumble-people-find': 'Sumble',
+  prospeo: 'Prospeo',
+  'prospeo-search-company': 'Prospeo',
+  'prospeo-search-person': 'Prospeo',
+  'ai-ark': 'AI-ARK',
+  'ai-ark-companies': 'AI-ARK',
+  'ai-ark-people': 'AI-ARK',
+  'ai-ark-reverse-lookup': 'AI-ARK',
+  leadsfactory: 'LeadsFactory',
+  findymail: 'Findymail',
+  'findymail-search-employees': 'Findymail',
+  'findymail-business-profile': 'Findymail',
+  'findymail-reverse-email': 'Findymail',
+  icypeas: 'Icypeas',
+  'icypeas-scrape-profile': 'Icypeas',
+  'icypeas-url-search-profile': 'Icypeas',
+  'icypeas-reverse-email-lookup': 'Icypeas',
+  wiza: 'Wiza',
+  builtwith: 'BuiltWith',
+  openmart: 'Openmart',
+  instantly: 'Instantly',
+
+  // --- LinkupAPI (LinkedIn data) -------------------------------------------
+  linkupapi: 'LinkupAPI',
+  'linkupapi-search': 'LinkupAPI',
+  'linkupapi-fundraising': 'LinkupAPI',
+  'linkupapi-hiring': 'LinkupAPI',
+  'linkupapi-search-profiles': 'LinkupAPI',
+  'linkupapi-by-domain': 'LinkupAPI',
+  'linkupapi-by-url': 'LinkupAPI',
+  'linkupapi-profile-enrich': 'LinkupAPI',
+  'linkupapi-email-reverse': 'LinkupAPI',
+  'linkupapi-validate': 'LinkupAPI',
+
+  // --- search_web ----------------------------------------------------------
+  serper: 'Serper',
+  exa: 'Exa',
+  'exa-contents': 'Exa',
+  jina: 'Jina',
+
+  // --- search_jobs ---------------------------------------------------------
+  career_site_jobs: 'Career Site Jobs',
+  linkedin_jobs_api: 'LinkedIn Jobs',
+
+  // --- search_ads ----------------------------------------------------------
+  google_ads: 'Google Ads',
+  linkedin_ad_library: 'LinkedIn Ad Library',
+  meta_ads: 'Meta Ads',
+  twitter_ads: 'X Ads',
+  reddit_ads: 'Reddit Ads',
+
+  // --- search_places / reviews ---------------------------------------------
+  google_maps: 'Google Maps',
+  google_maps_reviews: 'Google Maps',
+
+  // --- find_influencers ----------------------------------------------------
+  influencers_similar: 'Influencer Discovery',
+  influencers_discovery: 'Influencer Discovery',
+
+  // --- search_reddit -------------------------------------------------------
+  reddit: 'Reddit',
+
+  // --- search_seo (functional sub-actions) ---------------------------------
+  kw_search_volume: 'Keyword Search Volume',
+  kw_trends: 'Keyword Trends',
+  serp_google: 'Google SERP',
+  serp_bing: 'Bing SERP',
+  serp_youtube: 'YouTube SERP',
+  bl_summary: 'Backlink Summary',
+  bl_backlinks: 'Backlinks',
+  bl_referring: 'Referring Domains',
+  domain_tech: 'Domain Technologies',
+  domain_whois: 'Domain WHOIS',
+  labs_rank_overview: 'Rank Overview',
+  labs_ranked_kw: 'Ranked Keywords',
+  labs_competitors: 'Competitor Domains',
+  labs_kw_ideas: 'Keyword Ideas',
+  page_lighthouse: 'Lighthouse Audit',
+  page_content: 'Page Content',
+}
+
+/**
+ * Title-case an unmapped provider ID as a defensive fallback so a newly added
+ * provider still renders acceptably (and never leaks a raw slug). E.g.
+ * "some-new-vendor" → "Some New Vendor".
+ */
+function titleCaseId(id: string): string {
+  return id
+    .split(/[-_]/)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ')
+}
+
+/**
+ * Map an internal provider ID to a clean, branded display name. Falls back to a
+ * title-cased form of the ID when unmapped. Never returns "Apify".
+ */
+export function providerDisplayName(id: string): string {
+  return DISPLAY_NAMES[id] ?? titleCaseId(id)
+}